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Preface 


Manual Objectives 


The JAS System Library Routines Reference Manual describes the use and function of the syetem | 
Mbrary routines that may be called from MACRO-11 assembly a lac programs. 


| 
| 
| 
| 


Intended Audience 


This manual is intended for use by experienced MACRO-11 assembly euaanes programmers, IAS 
system managers, and applications programmers. a ae 


Document Structure 


Chapter 1 presents a general description of the services provided by the system library routines 
and their functional relationships. 

Chapter 2 describes the use and function of the register handling routines. 

Chapter 3 describes the use and function of the arithmetic routines. 

Chapter 4 describes the use and function of the input data conversion routines. 

Chapter 5 describes the use and function of the output data conversion routines. 

Chapter 6 describes the use and function of the output formatting routines. | 
Chapter 7 describes the use and function of the dynamic memory management routines. | 
Chapter 8 describes the use and function of the virtual memory management routines. | 
Chapter 9 summarizes the calling sequences of the system library routines. 


Appendix A presents a cross-reference system bibliography of other manuals that describe routines 
available to IAS system users. 


Appendix B describes a routine that enables a program to access modules in a universal library as 
if they were files. 


Associated Documents 

The following manuals are prerequisite sources of information for readers of this manual: 
°¢ The PDP-11 MACRO-11 Language Reference Manual 

* The JAS Task Builder Manual 


¢ The manuals referred to in Appendix A 


Readers should also refer to the IAS Documentation Directory and Master Index for descriptions of 
other documents associated with this manual. 
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Introduction 


The routines described in this manual were written to provide commonly needed capabilities for 
DIGITAL-supplied utilities. We supply documentation for them because the routines are general 
enough to be used regularly by most MACRO-11 programmers. Note, however, that the basic 
functionality of the routines described in this manual cannot be changed because of the parentiany, 
widespread effect it might have on our system utilities. 


The system library routines can be called by MACRO-11 assembly language programs to ae 
the following services: 


¢ Save and restore register contents to enable transfers of control between the calling: program 
and called subroutines 


* Perform integer and double-precision multiplication and division 

¢ Convert ASCII input data to internal binary and Radix-50 format 

¢ Convert internal binary and Radix-50 data to ASCII output data 

¢ Convert and format output data to produce text for a readable printout or display 


¢ Manage the dynamic memory space available to the task that requires a small- to-maderate 
amount of resident memory for data 


¢ Manage memory and disk file storage to accommodate tasks that require large amounts of 
memory for data that must be transferred between memory and a disk work file | 


This manual describes the procedures for calling the library routines from within the source 
program, the output that is returned to the executing task, and the interaction between the library 
routines and the executing task. 


The system library routines interface with each other to perform their various services| For 
example, the data conversion routines call the arithmetic routines to perform the required 
multiplication and division. All library routines preserve the contents of the calling task’ 8 registers, 
generally by calling the appropriate register handling routine to do the following: 


¢ Save register contents on the stack 
© Subsequently restore the contents of the registers 
° Return control to the calling task 


The data conversion and format control functions performed by the Edit Message Routine require 
calls to the output data conversion routines, which in turn call other routines. 


The virtual memory management routines function as an automatic control system to aiiseata and 
deallocate memory, maintain page addresses and status, and swap pages between memory and disk 
storage to accommodate large amounts of data in a limited amount of physical (dynamic) memory. 


The system library routines communicate with the calling task by means of registera where output 
is returned or by settings of the C bit in the Condition Code of the Processor Status Word. The 
-calling task can usually determine whether a requested service was successfully performed by 
examining the output register or registers or by testing the C bit setting when control is returned 
from the library routine. Exceptions to this procedure are described in the detailed discussions of 
given routines. 
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Introduction 


The system library routines are supplied to users as object code in the following files: 
¢ The system library file (SYSLIB.OLB), which contains the following routines: 

— Register handling routines (described in Chapter 2) 

— Arithmetic routines (described in Chapter 3) 

— Input and output data conversion routines (described in Chapters 4 and 5) 

— Output formatting routines (described in Chapter 6) 

— Dynamic memory allocation and release routines (described in Chapter 7) 

— Universal library access routines (described in Appendix B) 


¢ The memory management routines file (VMLIB.OLB), which contains the dynamic and virtual 
memory management routines. 


At task-build time, the Task. Builder will automatically search the system library file for any 
referenced routines. However, the VMLIB.OLB file must be specified at task-build time if a task 
has referenced the dynamic memory initialization routine (described in Chapter 7) or any of the 
virtual memory management routines (described in Chapter 8 of this manual). 


A summary of each procedure for using the system library routines is given in Chapter 9. This 
is quick-reference material provided for the MACRO-11 assembly language programmer who has 
become familiar with the detailed procedures that are explained in Chapters 2 through 8. 


Additional Executive and I/O routines available to LAS system users are described in other 
manuals. See the JAS Documentation Directory and Master Index for more information. 


If the task that includes system library routines also references a position-independent resident 
library, it is possible that program section names might conflict. Routines included in a task 
cannot reside in the same program section as routines referenced in the position-independent 
resident library. Table 1—1 lists the program section names and the system library routines that 
reside in each program section. If your task includes a routine that uses a program section listed 
in Table 1—1 and the task also references a position-independent resident library routine that uses 
the same program section, the Task Builder generates a fatal error. To determine how to include 
the code in your task and avoid a conflict of program section names, refer to the JAS Tusk Builder 
Manual 2654s see “© . . 
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Introduction ase 


Table 1-1 Program Section Names for SYSLIB Routines 
SYSLIB Routines 


Program Section 


Name Module Name Routine Name(s) 
.BLK. CATB $CDTB ! 
$COTB | 
CATS $CATS | 
CBTA $CBDAT | 
$CBOMG | 
$CBDSG | 
$CBOMG 
$CBOSG 
$CBTA 
$CBTMG 
CDDMG $CDDMG : 
CVTUC . $CVTUC | . 
CSTA $CSTA : 
EDDAT - $DAT 2 
 $TIM 
OD2CT DD2CcT | - 
.OD2CT | Fe 
SAVAL $SAVAL 7 j 
SAVVR $SAVVR | ° 
PURSD CATS5B (data) $CAT5B ; ae eens t 
EDTMG (data) $EDTMG Ga 
PURSI CATS5B (instruction) $CATSB i. sea 
EDTMG (instruction) $SEDTMG poe 
$$RESL SAVRG $SAVRG eae 
SAVR1 SAVR1 ee 
$$RESM ARITH $DIV . , ae Be 
| $MUL — , . pas Ts 
DARITH $DDIV 
$DMUL 
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Register Handling Routines 


The system library contains the following register handling routines: | 


e Save All Registers Routine ($SAVAL), which saves and subsequently restores Registers 0 
through 5 ! 


¢ Save Registers 3-5 Routine ($SAVRG), which saves and subsequently restores Registers 3 
through 5 


¢ Save Registers 0-2 Routine ($SAVVR), which saves and subsequently restores Registers 0 
through 2 


¢ Save Registers 1-5 Routine (.SAVR1), which saves and subsequently restores Registers 1 
through 5 | 


| 
The register handling routines function as coroutines to enable control swapping between 
themselves, a subroutine, and the original caller of the subroutine. The register eel routines 
are also called by other routines in the system library, as noted throughout this manual. 


To illustrate the effect of using the register handling routines, assume the following situation: 
1 An original caller calls a subroutine. 
2 The subroutine calls a register handling coroutine. | 


3 The coroutine preserves (pushes onto the stack) the contents of the specified registerg and 
issues a coroutine call back to the subroutine. | 


4 The subroutine executes to completion, then a return instruction is executed to swap control 
back to the coroutine. 


5 The coroutine restores (pops from the stack) the initial contents of the registers and returne to 
the original caller. | 
Figure 2~1 illustrates the control swapping function performed by the register handling routines. 


The register handling routines are called by other routines in the system library, as noted in this 
manual. 


Register Handling Routines 


Figure 2-1 Control Swapping of the Register Handling Routines 


ORIGINAL CALLER 
START Legend 
‘ CALL (subroutine) = JSR PC, subroutine 
4 RETURN = RTS PC 
oO 
ve) 
CALL (Subroutine) ——-.--» (Subroutine) 


JSR r,SSAVxx —————» $SAVxx (save registers) 


re) 

fe) as rs) 

ce) 0 re) 

0 0 re) 

re) 0 { (Issue coroutine call 
ro) 0 to subroutine) 
) ° » 

se) : | (restore registers) 
° re] 

o RETURN ° 

Qo ° 
ND 


m 


RETURN (to original caller) 


eee 
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$SAVAL 


$SSAVAL | 


The $SAVAL routine saves and subsequently restores Registers 0 through 5 for a subroutine. The 
$SAVAL routine functions as a coroutine that swaps control between itself, a subroutine, and the — 
original caller. 


To call the $SAVAL routine, include the following Jump to Subroutine instruction in your subroutine: 
JSR PC, $SAVAL 
The subroutine must return control to the $SAVAL routine with a RETURN source statement. 


On entry to the $SAVAL routine, the program stack contains the return address to the original caller|and 
the return address of the subroutine. The $SAVAL routine pushes the contents of registers 4 through 0 
to the stack. 


The $SAVAL routine moves the subroutine return address to the position following the contents of : 
Register 0 and moves the current contents of R5 to the stack above the contents of R4. 


The $SAVAL routine issues a coroutine call, in the form CALL @(SP)+, to swap control back to the 
subroutine. The coroutine call replaces the subroutine return address with the return address to the 
$SAVAL routine. When control returns to the subroutine the stack pointer points to $SAVAL's return 
address. The stack contains the following: 
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SSAVAL 


Return Address to Original Caller 


Register 5 


Register 4 


Register 3 
Register 2 


Register 1 


Register 0 


| Return Address to $SAVAL | 


The subroutine executes until a RETURN (RTS PC) instruction is executed, which swaps control back 
to the $SAVAL routine. The contents of RO through R5 are restored (popped from the stack) and the 
$SAVAL routine returns, by means of an RST PC instruction, to the original caller. 


NOTE: For $SAVAL to work properly (that is, return control to the original caller), the 
routine that calls $SAVAL must itself have been invoked by the CALL instruction (that 
is, JSR PC, subroutine). 
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$SSAVRG 


$SAVRG—Save registers 3-5 | 


The $SAVRG routine saves and subsequently restores Registers 3 through 5 for a subroutine. The 
$SAVRG routine functions as a coroutine that swaps control between itself, a subroutine, and the 
original caller. | 


To call the $SAVAG routine, the subroutine must contain the following Jump to Subroutine instruction: 


JSR RS, $SAVRG | 


| 
The subroutine must return control to the $SAVRG routine with a RETURN source statement. | 
On entry to the $SAVRG routine, the program stack contains the return address to the original caller 
and the contents of R5 of the original caller. The $SAVRG routine pushes the contents of registers 4 
and 3 to the stack, then pushes the current contents of R5 (return address to the subroutine) to the 
stack. 

| 


DESCRIPTION 


The $SAVRG routine copies the original contents back into R5 and issues a coroutine call in: 

the form CALL @(SP)+, to swap control back to the subroutine. The coroutine call replaces the 
subroutine’s return address with the return address to the $SAVRG routine. When control returns 
to the subroutine, the stack pointer points to $SAVRG’s return address. The stack contains th 
following: | 


Return Address to Original Caller : 


Register 5 contents of Original Caller 


Register 4 


Register 3 


Return Address to $SAVRG 


The subroutine executes until a RETURN (RTS PC) instruction is executed; this swaps control 
back to the $SAVRG routine. The contents of Registers 3 through 5 are restored (popped from the 
stack) and the $SAVRG routine RETURNs via an RTS PC instruction to the original caller. | 
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$SAVRG 


NOTE: For $SAVRG to work properly (that is, return control to the original caller), the 
routine that calls $SAVRG must itself have been invoked by the CALL instruction (that 
is, JSR PC, subroutine). 
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$SAVVR 


$SAVVR—Save registers 0—2 | 


The $SAVVR routine saves and subsequently restores Registers 0 through 2 for a subroutine. The 
$SAVVR routine functions as a coroutine that swaps contro! between itself, a subroutine, and the 
original caller. 


To call the $SAVVR routine, the subroutine must contain the following Jump to Subroutine ae 
JSR R2,$SAVVR | 


DESCRIPTION 


On entry to the $SAVVR routine, the program stack contains the return address to the original 
caller and the contents of Register 2 of the original caller. The $SAVVR routine pushes the contents 
of Registers 1 and 0 to the stack, then pushes the current contents of Register 2 (the return address 
to the subroutine) to the stack. 


The $SAVVR routine copies the original contents back into Register 2 and issues a coroutine call 
in the form CALL @SP)+, to swap control back to the subroutine. The coroutine call replaces the 
subroutine’s return address with the return address to the $SAVVR routine. When control returns 
to the subroutine, the stack pointer points to $SAVVR’s return address. The stack contains the 
following information: 


Return Address to Original Caller 


Register 2 contents of Original Caller 


Register 1 


Register 0 


Return Address to $SAVVR 


The subroutine executes until a return instruction (RTS PC) is executed; this swaps control back 
to the $SAVVR routine. The contents of Registers 0 through 2 are restored (popped from the stack). 
and the $SAVVR routine returns, by means of the RTS PC instruction, to the original caller. 
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SSAVRi 


.SAVR1—Save registers 1-5 


The .SAVR1 routine saves and subsequently restores Registers 1 through 5 for a subroutine. The 
.SAVR1 routine functions as a coroutine that swaps control between itself, a subroutine, and the original 
caller. 


To call the .SAVR1 routine, the subroutine must contain the following Jump to Subroutine instruction: 
JSR RS, .SAVR1 
The subroutine must return control to {he .SAVR1 routine with a RETURN source statement. 


DESCRIPTION 


On entry to the SAVR1 routine, the program stack contains the return address to the original 
caller and the contents of Register 5 of the original caller. The .SAVR1 routine pushes the contents 
of Registers 4, 3, 2, and 1, and the current contents of Register 5 (the return address to the 
subroutine) to the stack. 


The .SAVR1 routine copies the original contents back into Register 5 and issues a coroutine call, 
in the form CALL @SP)+, to swap control back to the subroutine. The coroutine call replaces the 
subroutine return address with the return address to the .SSAVR1 routine. When control returns 
to the subroutine, the stack pointer points to SAVRI1’s return address. The stack contains the 
following information: 
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SAVRI 


Return Address to Original Caller 


Register 5 contents of Original Caller 


Register 4 
Register 3 SO | 


Register 2 | 


Register 1 


Return Address to .SAVR1 


The subroutine executes until a return instruction (RTS PC) is executed; this swaps control back 
to the .SAVR1 routine. The contents of Registers 1 through 5 are restored (popped from the stack) 
and the .SAVR1 routine returns, by means of the RTS PC instruction, to the original caller. | 


NOTE: For .SAVR1 to work properly (that is, return control to the original caller), the 
routine that calls .SAVR1 must itself have been invoked by the CALL instruction ( that ve 
JSR PC, subroutine). 
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Arithmetic Routines | 


The system library contains four arithmetic routines that perform unsigned integer multiplication 


and division. This chapter describes the use and function of the following types of arithmetic 

routines: | 

| 

1 Integer Arithmetic Routines | 
The following routines perform arithmetic operations on 16-bit unsigned integer values: 


¢ The Integer Multiply Routine (SMUL), which multiplies integer values | 
¢ The Integer Divide Routine ($DIV), which divides integer values ; 
2 Double-Precision Arithmetic Routines | 
The following routines perform double-precision arithmetic operations: : 


¢ The Doubie-Precision Multiply Routine (SDMUL), which multiplies an unsigned | 
double-precision value by a single-precision multiplier to produce a double-precision product 


¢ The Double-Precision Divide Routine ($DDIV), which divides an unsigned double-precision 
dividend by an unsigned single-precision divisor to produce a double-precision result 


-$MUL 


$MUL—Integer Multiply Routine 


The $MUL routine multiplies two single-word unsigned integer input values to produce an unsigned 
double-word product. 


FORMAT 


CALL $MUL 


INPUT 


multiplier 
In Register 0: a single-word unsigned integer 


muitiplicand 
In Register 1: a single-word unsigned integer 


OUTPUT 
product (high-order) 
In Register 0: the high-order part of the result 


product (low-order) 
In Register 1: the low-order part of the result 


DESCRIPTION 


The $MUL routine preserves Registers 2 through 5 of the calling task. It does not return any error 
indications to the caller. 


EXAMPLE 


The following source statements call the $MUL routine to perform multiplication and store the 
results in the buffer WORK: 


WORK: .BLKW 2 7 OUTPUT BUFFER 


MOV #1200,R0 : PUTS MULTIPLIER IN REGISTER 0 

MOV #36,R1 ? PUTS THE MULTIPLICAND IN REGISTER 1 
CALL $MUL 7 CALLS S$MUL ROUTINE 

MOV RO, WORK 7 SAVES HIGH-ORDER PART OF RESULT 
MOV R1, WORK+-2 3 SAVES LOW-ORDER PART OF RESULT 
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$DIV—integer divide routine 


The $DIV routine performs unsigned integer division. 


FORMAT 


CALL $DIV 


INPUT 
dividend 


In Register 0: an unsigned integer | 


divisor 
In Register 1: an unsigned integer 


OUTPUT 


quotient 
In Register 0: the quotient 


remainder 
In Register 1: the remainder 


DESCRIPTION | 


The $DIV routine preserves Registers 2 through 5 of the calling task. It does not return any error 
indications to the caller. 


EXAMPLE 


The following source statements call the $DIV routine to perform Givasion and store the sebulta in 
Registers 0 and 1: | 


FRACTN: .WORD 1 ; BUFFER FOR REMAINDER 
MOV #36.,R0 ; SET DIVIDEND 
MOV #8.,R1 * SET DIVISOR 
CALL $DIV ; DIVIDE 
MOV R1, FRACTN ; SAVE REMAINDER 


a) 
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Doubie-Precision Multiply Routine 


Double-Precision Multiply Routine—$DMUL 


The $DMUL routine multiplies an unsigned double-precision value by an unsigned single-precision 
value to produce an unsigned double-precision product. 


FORMAT 
CALL $O0MUL 
INPUT 
multiplier 


In Register 0: an unsigned single-precision magnitude value 


multiplicand (high-order) 
In Register 2: the high-order part of an unsigned double-precision magnitude value 


multiplicand (low-order) 


In Register 3: the low-order part of the unsigned double-precision magnitude value 


OUTPUT 


product (high-order) 
In Register 0: the high-order part of the product 


product (low-order) 
In Register 1: the low-order part of the product 


DESCRIPTION 


The $DMUL routine preserves Registers 4 and 5 of the calling task, clears the C bit, and destroys 
the contents of Registers 2 and 3 upon return to the caller. The $DMUL routine does not return 
any error indications to the caller. 


EXAMPLE 


The following source statements call the $DMUL routine to multiply the number stored in 
Registers 2 and 3 by 127,9.and store the result in Registers 0 and 1: 


MOV R5,R2 - 3 HIGH-ORDER PART OF MULTIPLICAND 
MOV R4,R3 + LOW-ORDER PART OF MULTIPLICAND 
MOV #127.,R0 ; MULTIPLIER 

CALL SDMUL * MOLTIPLY BY 127. 
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$DDIV—Double-precision divide routine 


The $DDIV routine divides an unsigned double-precision integer dividend by an unsigned 
single-precision (15-bit) divisor to produce an unsigned double-precision result. 


FORMAT 


CALL $DDIV 


INPUT 


divisor 
In Register 0: an unsigned double-precision integer 


dividend (high-order) 


In Register 1: the high-order part of an unsigned single-precision integer 
dividend (low-order) 


In Register 2: the low-order part of an unsigned single-precision integer 


OUTPUT 


remainder 


In Register 0: the remainder 


guotient (high-order) 
In Register 1: the high-order part of the quotient 


quotient (low-order) 
In Register 2: the low-order part of the quotient 


DESCRIPTION 


The $DDIV routine preserves the contents of Registers 3 through 5 of the calling task. The $DDIV 
routine does not return any error conditions to the caller. 


EXAMPLE 


The following source statements call the $DDIV routine to perform division and store the results 
in Registers 0, 1, and 2:. ; 


SDDIV 
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~-BLKW 2 

»-BLKW 2 

-BLKW 1 

MOV #150,R0 
MOV DVD, R1 
MOV DVD+2, R2 
CALL SDDIV 
MOV R1, QUOT 
MOV RZ, QUOT+2 
MOV RO, RMAIN 


“e ‘a Se Se 


ses Ye “es Se 


we 


“a 


BUFFER TO STORE HIGH-ORDER OF DIVIDEND 
BUFFER TO STORE HIGH-ORDER OF QUOTIENT 
BUFFER FOR REMAINDER 

PUT DIVISOR IN REGISTER 0 

SET UP HIGH-ORDER PART OF DIVIDEND 

SET UP LOW-ORDER PART OF DIVIDEND 

CALL SDDIV ROUTINE 

PUT HIGH-ORDER PART OF QUOTIENT IN BUFFER 
PUT LOW-ORDER PART OF QUOTIENT IN BUFFER 
POT REMAINDER IN RMAIN 


4.1 


4.2 


4.3 


Input Data Conversion Routines 


The input data conversion routines accept ASCII data as input and convert it to the specified 
numeric representation. The following three types of routines perform input data conversion: 


¢ ASCII to binary double-word conversion routines, which accept ASCII decimal or octal input 
numbers and convert them to double-word binary numbers | 


¢ ASCII to binary conversion routines, which accept ASCII decimal or octal input niavibars and 
convert them to single-word binary numbers | 


e ASCII to Radix-50 conversion routines, which accept the Radix-50 set of ASCII characters as 
input and convert them to Radix-50 internal format 


ASCIil to Binary Double-Word Conversions 


The following system library routines convert ASCII input numbers to double-word binary 
numbers: 


¢ The Decimal to Binary Double-Word Routine (.DD2CT), which accepts ASCII decimal numbers 
as input and converts them to double-word binary format | 


¢ The Octal to Binary Double-Word Routine (.OD2CT), which accepts ASCII octal numbers as 
input and converts them to double-word binary format 


ASCIl to Binary Conversions | 


The following routines convert unsigned ASCII input numbers to single-word unsigned binary 
numbers: 


© The Decimal to Binary Conversion Routine ($CDTB), which accepts ASCII decimal numbers as 
input and converts them to single-word binary format 


¢ The Octal to Binary Conversion Routine ($COTB), which accepts ASCII octal numbers as input 
and converts them to single-word binary format 


These routines call the Integer Multiply Routine (SMUL) to perform the multiplication required for 
the conversion. 


ASCIl to Radix-50 Conversions 


The following routines convert ASCII alphanumeric input characters to 16-bit Radix-50 values: 


¢ The ASCII to Radix-50 Conversion Routine ($CAT5), which accepts input characters from the 
ASCII character Radix-50 subset and converts them to Radix-50 format! 


1 See the PDP-11 MACRO-11 Language Reference Manual! for a complete listing of the Radix- 50 character oot and ASCII 
equivalents. 
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Input Data Conversion Routines 


¢ The ASCII with Blanks to Radix-50 Conversion Routine ($CAT5B), which accepts input 
characters from the ASCII character Radix-50 subset and blank characters and converts 
them to Radix-50 format! 


Both routines call the Integer Multiply Routine (SMUL) to perform the multiplication required for 
the conversion. 
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.DD2CT—Decimal to binary doubie-word routine 


The .DD2CT routine converts a signed ASCII decimal number string to a double-length (2-word) signed 
binary number. 


FORMAT 


CALL .DD2CT 


INPUT 


output address 
In Register 3: the address of the 2-word output field where the converted number is to be stored 


number input characters 


In Register 4: the number of characters in the string to be converted 


input string address | 
In Register 5: the address of the character string to be converted 


OUTPUT 


binary result (high-order) 
In word 1 of the output field: the high-order 16 bits of the converted number 


binary result (low-order) 
In word 2 of the output field: the low-order 16 bits of the converted number 


Condition code 


C bit = Clear if conversion was successful 
C bit = Set if an illegal character was found and conversion was incomplete 


DESCRIPTION 


The .DD2CT routine accepts leading plus (+) or minus (~) signs and a trailing period (.) in the 
string to be converted. A preceding pound sign (#) forces octal conversion; a pound sign and a 
period in the same input string is invalid. The numbers 0 to 9 are acceptable characters in the 
decimal number string itself. Any other characters in the string will cause the .DD2CT routine to 
eranets the conversion procedure. The value range of a decimal number to be converted is ~ 2?! 
to +2°* — 1. 


The .DD2CT routine saves and restores all of the calling task’s registers. 
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EXAMPLE 


The following source statements call the .DD2CT routine to convert an ASCII decimal number 
string (pointed to by buffer ICHR), store the binary result in the address pointed to by buffer 
BOUT, and check the results upon return: 


ICHR: -ASCII /1234567./ 


- EVEN 
BOUT: - BLKW 2 
MOV #BOUT, R3 ; GET ADDRESS OF THE 2-WORD OUTPUT FIELD 


MOV #10,R4 ; GET THE NUMBER OF INPUT CHARACTERS 


MOV #ICHR, RS + GET ADDRESS OF THE INPUT CHARACTER STRING 
CALL -DD2CT 7 CONVERT THE STRING 
BCS 1005S 7 BRANCH IF C BIT SET (CONVERSION WAS NOT SUCCESSFUL) 
. 7 PROGRAM CONTINUES 
100S: CALL ERR 7; CALL ROUTINE TO OUTPUT ERROR MESSAGE 


OD2CT 


-OD2CT—Octal to binary double-word routine 


The .OD2CT routine converts an ASCII octal number string to a double-length (2-word) binary number. 


FORMAT | 


CALL .OD2CT 


INPUT 


output address | 
In Register 3: the address of the 2-word output field in which the converted number is to be stored 


number input characters 


In Register 4: the number of characters in the string to be converted 


input string address 
In Register 5: the address of the character string to be converted 


OUTPUT | | 


binary result (high-order) 
In word 1 of the output field: the high-order 16 bits of the converted number 


binary result (low-order) 
In word 2 of the output field: the low-order 16 bits of the converted number 


Condition Code | | 


C bit = Clear if conversion was successful 


C bit = Set if an illegal character was found and conversion was incomplete 


DESCRIPTION | 
| 


The .OD2CT routine accepts leading plus ( +) or minus ( — ) signs and a trailing period (.) in 
the string to be converted. A preceding pound sign ( #) is accepted but unnecessary; a pound sign 
and a period in the same input string is invalid. A trailing period forces decimal conversion. (This 
is because the .OD2CT routine is an entry point in the .DD2CT routine, which converts decimal 
number strings to binary double-word values.) Acceptable characters in the octal number string 
itself are the numbers 0 to 7. 


The .OD2CT routine terminates the conversion process if you use any other characters in thl 
ASCII octal number string. | | 


The value range of an octal number you can convert is —2°! to +231 - 1. 


4-5 


.OD2CT 


The .OD2CT routine saves and restores all of the calling task’s registers. 


EXAMPLE 


The following source statements call the .OD2CT routine to convert an ASCII octal number string 
(pointed to by buffer ICHR), store the binary result in the address pointed to by buffer BOUT, and 
check the results upon return: 


ICHR: ASCII /2461357/ 
EVEN 
BOUT:  .BLKW 2 
MOV #BOUT, R3 ; GET ADDRESS OF THE 2-WORD OUTPUT 
MOV #7,R4 ; GET THE NUMBER OF INPUT CHARACTERS 
MOV #ICHR, R5 ; GET ADDRESS OF THE INPUT CHARACTER STRING 
CALL .OD2CT ; CONVERT THE STRING 
BCS 1008 ; BRANCH IF C BIT SET (INPUT STRING 
, ; CONVERSION WAS NOT SUCCESSFUL) 
; ; IF C BIT CLEAR, CONVERSION WAS SUCCESSFUL 
: ; AND THE PROGRAM CONTINUES 
100$: CALL ERR ; CALL ROUTINE TO OUTPUT ERROR MESSAGE 
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$CDTB—Decima! to binary conversion routine 


The $COTB routine converts an unsigned ASCII decimal number to binary format. 


FORMAT 


CALL $CDTB | 


INPUT | | 


input buffer address 
In Register 0: the address of the first byte of the ASCII decimal character string to be converted 


OUTPUT | 
next byte address i 
In Register 0: the address of the next byte of the input buffer 
binary number | 


In Register 1: the converted number 


terminator 
In Register 2: the terminating character of the input buffer 


DESCRIPTION 


The numbers 0 to 9 are valid characters in the input decimal number. All other input characters 
are invalid and are not converted by this routine. The end of a string of numbers must be | 
marked by a terminating character, which can be any ASCII character except the numbers 0 

to 9. Examples of terminating characters are a blank, tab character, alphabetic character, and 
special symbol. Leading blanks and tab characters are ignored. 


The maximum value of a decimal number that can be converted by the $CDTB routine is 65 535. 
Numbers of greater value will cause indeterminate results since the $CDTB routine does not check 
the value range of an input number. Also, the routine does not return a significant Condition Code 
setting to the calling task. 


Because the $CDTB routine returns the address of the next byte in the input buffer to the ee 
task, you can convert successive strings by setting up a processing loop back to the CALL cuts 
statement (see the example for this routine). 
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$CDTB calls the $SAVRG routine to save and restore Registers 3 through 5 of the calling task. 


NOTE: You can determine, in the task, whether an input string was successfully 
converted by testing the contents of Register 2. If the contents are other than the 
expected terminating character, the conversion was incomplete because the routine 
found an invalid character in the input string. 


EXAMPLE 


The following source statements define a processing loop, using the $CDTB routine, to convert a 
series of ASCII decimal character strings to binary numbers. This example uses the tab character 
as the terminating character of each string and the space character as the terminating character of 
the input buffer. If converted successfully, the binary numbers will be stored in the buffer BNUM: 


IBOF: »ASCII /123/<11>/4567/<11>/89/<11>/87654/<40> 
- EVEN 


BNUM: - SLKW 4 ; BUFFER FOR CONVERTED NUMBERS 


MOV #BNUM, R4 
MOV #IBUF, RO 
LOOP : CALL SCDTB 
MOV Rl, (R4)+ 
CMP #11,R2 


GET THE OUTPUT BUFFER ADDRESS 

SET UF INPUT BUFFER ADDRESS 

CONVERT THE STRING 

SAVE CONVERTED STRING 

COMPARE ASCII TAB (HT) VALUE TO TERMINATING 
CHARACTER RETURNED IN REGISTER 2 

IF EQUAL, STRING SUCCESSFULLY CONVERTED, 
GO BACK THROUGH LOOP TO CONVERT NEXT INPUT 

STRING POINTED TO BY REGISTER 0 

COMPARE SPACE VALUE (40) WITH TERMINATING 

CHARACTER IN REGISTER 2 


BEQ LOOP 


CMP #40, R2 


BEQ 10$ IF EQUAL, CONTINUE PROGRAM (ALL INPOT 
HAS BEEN CONVERTED SUCCESSFULLY) 
JMP ERR IF NOT EQUAL, ILLEGAL CHARACTER IN INPUT 


STRING CAUSED CONVERSION TO TERMINATE; HENCE 
INPUT IS ERRONEOUS; GO TO ERROR ROUTINE 
PROGRAM CONTINUES 


Ay en, et en) Ye) ey ee YY Ye) oe YY a, Te Pd 


108; 


$COTB 


$COTB—Octal To Binary Conversion Routine 
The $COTB routine converts an unsigned ASCII octal number to binary format 
FORMAT | | 


CALL $COTB 


INPUT 


input buffer address | 
In Register 0: the address of the first byte of the ASCII octal character string to be converted 


OUTPUT | 


next byte address 
In Register 0: the address of the next byte of the input buffer 


binary number 
In Register 1: the converted number 


terminator 
In Register 2: the terminating character of the input buffer 


DESCRIPTION | 


The characters 0 to 7 are valid in the input octal number. The maximum value of an octal number 
that can be converted by the $COTB routine is 177777. The end of a string must be marked. by 

a terminating character, which can be any ASCII character except the numbers 0 to 7. Examples 
of terminating characters are a blank, tab character, alphabetic character, and special symbal. 
Leading blanks and tab characters are ignored. 


$COTB calls the $SAVRG routine to save and restore Registers 3 through 5 of the calling task. 
NOTE: You can determine, in the task, whether an input string was successfully 
converted by testing the contents of Register 2. If the contents are other than the 
expected terminating character, the conversion was incomplete because the routine 
found an invalid character in the input string. 
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$COTB 


EXAMPLE 


The following source statements define a processing loop, using the $COTB routine, to convert a 

series of ASCII octal character strings to binary numbers. The example uses the tab character as 
the terminating character of each string and the space character as the terminating character of 
the input buffer. If converted successfully, the binary numbers will be stored in the buffer BNUM: 


IBUF: .ASCII /012/<11>/3456/<11>/76/<11>/54321/<40> 
- EVEN 
BNUM: .BLKW 4 ; BUFFER FOR CONVERTED STRINGS 


MOV #BNUM, R4 
MOV #IBOF, RO 
LOOP: CALL SCOTB 
MOV R1, (R4)+ 
CMP #11,R2 


GET OUTPUT BUFFER ADDRESS 

SET UP INPUT BUFFER ADDRESS 

CONVERT THE STRING 

SAVE CONVERTED STRING 

COMPARE ASCII TAB (HT) VALUE TO TERMINATING 
CHARACTER RETURNED IN REGISTER 2 

IF EQUAL, STRING SUCCESSFULLY CONVERTED, 
GOES BACK THROUGH LOOP TO CONVERT NEXT INPOT 

STRING POINTED TO BY REGISTER 0 

COMPARES SPACE VALUE (40) WITH TERMINATING 

CHARACTER IN REGISTER 2 


se Se Se Se 


BEQ LOOP 


CMP #40,R2 


™e Se Se Se Fe Mae Me ONS 


BEQ 10$ TF EQUAL, CONTINUES PROGRAM (ALL INPUT 
; HAS BEEN CONVERTED SUCCESSFULLY) 
JMP ERR ; IF NOT EQUAL, ILLEGAL CHARACTER IN INPUT 


STRING CAUSED CONVERSION TO TERMINATE; HENCE 
INPUT IS ERRONEOUS; GOES TO ERROR ROUTINE 
PROGRAM CONTINUES 


we Me Ms 


108: 
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$CAT5—ASCII to Radix-50 Conversion Routine 


The $CATS5 routine converts up to three ASCIl characters to a 16-bit Radix-50 value. 


FORMAT 


CALL $CAT5 : 


INPUT 


input buffer address 
In Register 0: the address of the first character in the ASCII string you want to convert 


period disposition flag 
In Register 1, one of the following values: 


R1 = 0 if the period is a terminating character 
R1 = 1 to specify that the period is a valid character to be converted to Radix-50 


OUTPUT | | 


next input character 
In Register 0: the address of the next character of the input string 


Radix-50 value 
In Register 1: the converted Radix-50 value 


terminator 


In Register 2: the terminating character or the invalid character that caused termination 


Condition Code 
C bit = Clear if conversion was complete 


C bit «= Set it conversion was incomplete 


DESCRIPTION | 


The following characters are valid in the ASCII string to be converted: 
© The alphabetic characters A to Z 
¢ The numeric characters 0 to 9 


¢ The dollar sign ($) and period (.) 
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$CATS5 


For complete conversion, the string must contain three valid characters. If the string contains 
fewer than three valid characters, the $CAT5 routine will convert them but will set the C bit 

to indicate an incomplete conversion. Invalid characters cause the $CAT5 routine to terminate 
conversion. In this case, the output will be the valid character or characters and trailing blank or 
blanks, in binary format. 


A blank character (space) in the ASCII character string causes the $CAT5 routine to terminate. If 
you include blanks as valid characters in the string, call the $CAT5B routine to do the conversion. 


Since the address of the next character in the input string is returned in Register 0, you can 
convert successive strings by resetting Register 1 and setting up a processing loop back to the 
CALL $CAT5 statement. 


The $CAT5 routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
calling task. 


NOTE: You can determine, in the task, whether conversion was complete by testing the 
C bit in the Condition Code or the contents of Register 2. 


EXAMPLE 


The following source statements define a subroutine that calls the $CAT5 routine to convert ASCII 
input data to Radix-50 format: 


ASDAT: .ASCII /ABC.DEF.HIJ./ ; STRINGS TO BE CONVERTED 
- EVEN 
RADS: -BLKW 3. ? OUTPUT BUFFER 


GET OUTPUT ADDRESS 
SET LIMIT TO LOOP 
SET UP THE ADDRESS OF THE FIRST ASCII CHARACTER 


18: CLR R1 + SPECIFY THAT PERIOD IS CONVERSION TERMINATOR 
CALL S5CATS 7; CONVERT ASCII RADIX=-50 
Bcc 2s ; BRANCH IF C BIT IS CLEAR (CONVERSION COMPLETE) 
JMP INER ; JUMP TO INPUT ERROR ROUTINE IF 
; C BIT IS SET (CONVERSION INCOMPLETE) 
28: MOV R1, (R4)+ 7; STORE CONVERTED CHARACTER 
DEC RS 
BGT 1$ 7 PROCESS NEXT STRING 
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SCAT5B—ASCII with Blanks to Radix-50 Conversion 
Routine 


The $CAT5B routine converts an ASCII 3-character string, including blank characters, to a 16- bit 
Radix-50 value. 


FORMAT 


CALL $CAT5B 


INPUT | 


input buffer address 


In Register 0: the address of the first character in the ASCII string you want to convert | 


period disposition flag 


In Register 1, one of the following values: 


R1 = O if the period is a terminating character 
Ri = 1 to specify that the period is a valid character to be converted to Radix-50 


OUTPUT 


next input character 
In Register 0: the next character of the input string 


Fiadix-50 value 
In Register 1: the converted Radix-50 value, one to three characters in length 


| 
terminator | 


In Register 2: the terminating character or the invalid character that caused termination 


Condition Code 


| 

; ’ ; | 

C bit = Clear if conversion was compiete | 
| 

| 


C bit = Set if conversion was incomplete 


DESCRIPTION 


The following characters are valid in the ASCII string to be converted: 
¢ The alphabetic characters A to Z 


© The numeric characters 0 to 9 


$CAT5B 


e The dollar sign ($), period (.), and blank (space) 


For complete conversion, the string must contain three valid characters. If the string contains 
fewer than three valid characters, the $CAT5B routine will convert them but will set the C bit 
to indicate an incomplete conversion. Invalid characters cause the $CAT5B routine to terminate 
conversion. In this case, the output will be the valid character or characters and trailing blank or 
blanks, in binary format. 


Since the address of the next character in the input string is returned in Register 0, you can 
convert successive strings by resetting Register 1 and setting up a processing loop back to the 
CALL $CATS5B statement. 


$CATS5B calls the $SAVRG routine to save and restore Registers 3 through 5 of the calling task. 


NOTE: You can determine, in the task, whether conversion was compiete by testing the 
C bit in the Condition Code or the contents of Register 2. 


EXAMPLE 


The following source statements call the $CAT5B routine to convert a 3-character ASCII string to 
Radix-50 format: 


INSTR: .ASCII /IND/ 7; ASCII INPUT STRING 
-BYTE iS ; STRING TERMINATOR 
EVEN 
MOV INSTR, RO POINT TO THE ASCII INPUT STRING 


CALL SERR NO, CALL SYNTAX ERROR ROUTINE 


PROGRAM CONTINUES 


MOV #1,R1 7 SPECIFY PERIOD IS VALID CHARACTER 
CALL $CATSB ; CONVERT IT TO RADIX-50 

Bcc 10$ + WERE CHARACTERS CONVERTED? 

CMPB #15,R2 7 NO -- WAS TERMINATOR A <CR> ? 

BEQ 10$ + EQ -- YES 


4-14 


Output Data Conversion Routines 


The output data conversion routines convert internally stored numeric data to ASCII chatacters. 
The following four groups of routines convert output data: | 


¢ Binary to decimal conversion routines, which convert binary data to one of the following 
formats: 


2-digit day date, in the range 01 to 31 


- 6-digit unsigned decimal magnitude number 
~ 5-digit signed decimal number 
- Decimal number up to nine digits in length 


* Binary to octal conversion routines, which convert binary numbers to one of the following octal 
numbers: | 


~ 6-digit unsigned octal magnitude number 
~ 6-digit signed octal number | 
- 3-digit octal number | 

* A general-purpose binary conversion routine that converts binary data to ASCII format. Note 
that the preceding conversion routines format their output according to internally-defined 
conversion parameters. The $CBTA routine allows you to determine the format of the output 
by specifying the conversion parameters. You can call this routine directly, or you can call it 


indirectly when you use the binary to decimal or octal routines. These routines pass predefined 
conversion parameters to the $CBTA routine. | 


® A Radix-50 to ASCII conversion routine, which converts a Radix-50 value to a 3-character 
ASCII string 


The output data routines described in this chapter are called by the Edit Message ealh 
($EDMSG; described in Chapter 6) to convert data to be formatted for output to printers or e-cieplay 
devices. 


The following four system library routines convert internally formatted binary numbers to external 
ASCII decimal format: 


* Binary Date Conversion Routine ($CBDAT), which converts an internally stored binary date to 
a 2-digit decimal number 


* Convert Binary to Decimal Magnitude Routine (§CBDMG), which converts an internally stored 
binary number to a 5-digit unsigned ASCII decimal magnitude value 


® Convert Binary to Signed Decimal Routine ($CBDSG), which converts an steetaliyat stored 
binary number to a 5-digit signed ASCII decimal number 


* Convert Double-Precision Binary to Decimal Routine ($CDDMG), which converts a 
double-precision, unsigned binary number to an ASCII decimal number of nine or fewer 
digits 


These routines use predefined conversion parameters that are passed to the general-purpose 
conversion routine ($CBTA), which performs the actual binary to ASCII conversion. 


| Output Data Conversion Routines 


Note that these routines do not add an extra space for the minus sign (~) to the predefined 
field-width parameter. If you are converting a negative number, expect that one of the spaces 
in the output area will be used for the minus sign. 
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$CBDAT—Binary date conversion routine 


The $CBDAT routine converts an internally stored binary date to a 2-digit unsigned decimal number. 


FORMAT 


CALL $CBDAT 


The $CBDAT routine uses the following predefined conversion parameters: 


Radix =» 10 
Field width = 2 characters 
Sign flag = UNSIGNED 


INPUT 


output address ! 
In Register 0: the starting address of the output area that will store the converted 2-byte date 


input date 
In Register 1: the date (a binary value in the range 01 to 31) 


zero suppression indicator 
In Register 2, one of the following values: 


R2 = 0 to specify suppression of leading zeros in the converted date (the date will be left-justified) 
R2 = Nonzero to specify no suppression of leading zeros 


OUTPUT 


converted date 
In the specified output area: the converted day date (in ASCII decimal format) 


next output address 
In Register 0: the next available address (the pointer to the location following the last digit stored) 


DESCRIPTION 


The $CBDAT routine pushes the predefined conversion parameters on the stack. It then passes the 
conversion parameters in Register 2 to the General Purpose Binary to ASCII Conversion Routine 
($CBTA), which performs the actual conversion of the binary number. 


The $CBDAT routine calls the $SAVRG routine to save and restore Registers 3 through 5 of ‘the 
calling task, and destroys the contents of Registers 1 and 2. The $CBDAT routine does not return 
any error conditions to the caller. 
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EXAMPLE 


The following source statements call the $CBDAT routine to convert a binary date in the buffer 
BDAT and store the converted date in the buffer ASDAT: 


OUTPUT BUFFER 


ze 


ASDAT: .BLKB 2 
EVEN 
BDAT: .WORD 1 7; INPUT ~- BINARY DATE aa 
MOV #ASDAT, RO ; POTS THE ADDRESS OF OUTPUT AREA IN REGISTER 0 
MOV BDAT, Ri ; PUTS THE BINARY DATE, AT BDAT, IN REGISTER 1 


CLR R2 CLEARS REGISTER 2 TO ZERO TO SPECIFY THAT LEADING 
; ZEROS ARE TO BE SUPPRESSED 
CALL SCBDAT 7; CALLS THE S$CBDAT ROUTINE 


$CBDMG 


$CBDMG—Convert binary to decimal magnitude 
routine 


The $CBDMG routine converts an internally stored binary number to a 5-digit unsigned ASCII decitnal 
magnitude number. 


FORMAT 


CALL $CBDMG 


The $CBDMG routine uses the following predefined conversion parameters: 
Radix = 10 

Field width = 5 characters 

Sign flag = UNSIGNED 


INPUT 


output address | 
In Register 0: the starting address of the output area that will contain the converted 5- et) 
number 


input number 


In Register 1: the unsigned binary number you want to convert 


| 
zero suppression indicator | 
In Register 2, one of the following values: . 
R2 = 0 to specify suppression of leading zeros in the converted number (the number will be left-justified) | 
R2 «= Nonzero to specify no suppression of leading zeros 


OUTPUT | | 
result , 


In the specified output area: the converted number, a maximum of five digits in length 


next output address 3 
In Register 0: the next available address in the output area (the pointer to the location following 
the last digit stored) 


5-5 


$CBDMG 


DESCRIPTION 


The $CBDMG routine pushes the predefined conversion parameters on the stack. It then passes 
the conversion parameters in Register 2 to the General Purpose Binary to ASCII Conversion 
Routine ($CBTA), which performs the actual conversion of the binary number. 


The $CBDMG routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
calling task. It destroys the contents of Registers 1 and 2. The $CBDMG routine does not return 
error conditions to the caller. 


EXAMPLE 


The following source statements call the $CBDMG routine to convert a binary number stored in 
the buffer $IEXT and store the converted 5-digit ASCII decimal magnitude number in the buffer 
.TEXT: 


«TEXT: .BLKB 5 ; OUTPUT BUFFER 
-EVEN 
STEXT: .WORD 2765. + INPUT VALUE 
MOV #. TEXT, RO ; GET OUTPUT BUFFER 
MOV SIEXT,R1 ? GET BINARY VALUE 
CLR R2 ; SUPPRESS ZEROS 
CALL $CBDMG # CONVERT TO ASCII (DECIMAL) 


$CBDSG 


$CBDSG—Convert binary to signed decimal routine 


The $CBDSG routine converts an internally stored binary number to a 5-digit signed ASCII decimal 
number. 


FORMAT 
CALL $C8BDSG 


The $CBDSG routine uses the following predefined conversion parameters: 
Radix = 10 

Field width = 5 characters 

Sign flag = SIGNED 


INPUT 


output address 
In Register 0: the starting address of the output area that will store the converted 5-digit number 


input number 
In Register 1: the binary number to be converted 


zero suppression indicator 
In Register 2, one of the following values: 


R2 « 0 to suppress leading zeros in the converted number (the output number will be left-justified) 
R2 «= Nonzero to specify no suppression of leading zeros | 


OUTPUT 


result 


In the specified output area: the converted Panes a maximum of five digits in length 


next output address 


In Register 0: the next available address in the output area (the pointer to the location following 
the last digit stored) 


DESCRIPTION 


The $CBDSG routine automatically pushes the predefined conversion parameters on the stack. 
It then passes the conversion parameters in Register 2 to the General Purpose Binary to ASCII 
Conversion Routine ($CBTA), which performs the actual conversion of the binary number. 


5-7 


-$CBDSG 


The $CBDSG routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
calling task, and does not save the contents of Registers 1 or 2. The $CBDSG routine does not 


return error conditions to the caller. 


EXAMPLE 


The following source statements call the $CBDSG routine to convert a binary value stored in the 
buffer FERR and store the converted 5-digit ASCII decimal number in the buffer ER2NUM: 


ER2: -ASCIT $1I/0 ERROR CODE:$ ; ERROR MESSAGE 
ERZNUM: .BLKB 5 ; OUTPUT BUFFER 
-BVEN 
FILERR: MOVB F.ERR (RO) ,R1 ; GET ERROR CODE TO CONVERT 


MOV #ER2ZNUM, RO ; POINT TO OUTPUT BUFFER 
CLR R2 + SUPPRESS LEADING ZEROS 
CALL SCBDSG ; CONVERT ERROR CODE 
MOVB #’., (RO) + ; PUT IN DECIMAL POINT 


$CDDMG—Convert double-precision binary to 
decimal routine 
The $CDDMG routine converts a double-precision, unsigned binary number to an unsigned ASCII 


decimal number, up to nine digits, less than or equal to 65,536x10*. If the number contains more than 
nine digits, the routine inserts a string of five ASCII asterisk symbols In the output area. 


FORMAT 
CALL $CDDMG 


INPUT 


output address 
In Register 0: the starting address of the output area 


input address 


In Register 1: the address of the 2-word input area containing the double-precision number | 


zero suppression indicator | 
In Register 2, one of the following values: 
R2 = Oto specify suppression of leading zeros in the converted date (the date will be left-justified) 


R2 «= £Nonzero to specify no suppression of leading zeros 


NOTE: If the five most significant digits are zeros, they will be suppressed automatically, 
regardless of the setting of the suppression indicator. 


OUTPUT | 


result 


In the output area: the converted ASCII number 


next output address 
In Register 0: the pointer to the next available address in the output storage area 


NOTE: If the number was converted successfully, the output area will contain from 
four to nine digits. If the conversion attempt results in a decimal number greater than 
65,536x10* or longer than nine digits, the $CDDMG routine prints a string of five ASCII 


asterisks in the output area. 


DESCRIPTION | 


The $CDDMG routine performs the following actions: 
¢ Calls the $SAVRG routine to save and restore Registers 3 through 5 of the calling task 
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¢ Calls the $DDIV routine to perform the double-precision division 
¢ Calls the $CBTA routine to perform the actual ASCII conversion 
e Destroys the contents of Registers 1 and 2 


EXAMPLE 


The following source statements call the S3CDDMG routine to convert a double-precision number, 
pointed to by the buffer DPWRD, and store the converted ASCII decimal number in the buffer 
ASDN: 


ASDON: .BLKB 9. ¢ OUTPUT BUFFER 
-EVEN 

DPWRD: .BLKW 2 
MOV #ASDN, RO 
MOV #DPWRD, RL 


INPUT BUFFER 
PUTS ADDRESS OF OUTPUT AREA IN REGISTER 0 
PUTS STARTING ADDRESS OF DOUBLE- 

PRECISION INPUT WORD IN REGISTER 1 
PUTS NONZERO IN REGISTER 2 (SETS THE ZERO 

INDICATOR FLAG TO 1) TO SPECIFY 

THAT LEADING ZEROS ARE NOT TO 
BE SUPPRESSED 

CALLS THE $CDOMG ROUTINE 
COMPARES AN ASCII ASTERISK SYMBOL WITH 

A BYTE OF THE CONVERTED NUMBER 


te Ne Ne Ne 


MOV #4.,R2 


CALL SCDDMG 
CMPB #’ *, ASDN 


BNE 10$ IF NOT EQUAL, CONVERSION WAS SUCCESSFUL 
AND PROGRAM CONTINUES 
JMP ERR IF EQUAL, JUMP TO ERROR ROUTINE ERR (MORE 


THAN NINE DIGITS WERE CONVERTED AND THE 
OUTPUT DATA IS INVALID) 


we “Ne %e Ye Ye Ne Ye Ye Na Ne Se Ne 


10S: 


NOTE: The source statements also check the results and call an error routine if 
$CDDMG was not successful. 
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Output Data Conversion Routines 


The following three routines convert internally formatted binary numbers to external ASCII octal 
format: 


e Convert Binary to Octal Magnitude Routine ($CBOMG), which converts an internally stored 
binary number to a 6-digit unsigned ASCII octal magnitude number 


¢ Convert Binary to Signed Octal Routine ($CBOSG), which converts an internally stored binary 
number to a 6-digit signed ASCII octal number 


¢ Convert Binary Byte to Octal Magnitude Routine ($CBTMG), which converts an internally 

stored binary byte to a 3-digit unsigned ASCII octal number | 
These routines pass predefined conversion parameters to the general-purpose conversion soulne 
($CBTA), which performs the actual binary to ASCII conversion. 


Note that these routines do not add an extra space for the minus sign (—) to the predefined | 
field-width parameter. If you are converting a negative number, expect that one of the spaces 
in the output area will be used for the minus sign. 
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$CBOMG—Convert binary to octal magnitude 
routine 


The $CBOMG routine converts an internally stored binary number to a 6-digit unsigned ASCIl octal 
magnitude number. 


FORMAT 


CALL $CBOMG 


The $CBOMG routine uses the following predefined conversion parameters: 
Radix = 8 

Fieid width = 6 characters 

Sign flag = UNSIGNED 


FE a ie a a | LS AN OS TS ESR Ne SS LM ence h E T ae 


INPUT 


output address 

In Register 0: the starting address of the output area in which the converted 6-digit number is to 
be stored 

input number 

In Register 1: the binary number you. want to convert 

zero suppression indicator 

In Register 2, one of the following values: 


R2 «= Oto specify suppression of leading zeros in the converted number (the number will be left-justified) 
R2 = Nonzero to specify no suppression of leading zeros 


OUTPUT 


result 


In the specified output area: the converted number, a maximum of six digits in length 


next output address 
In Register 0: the next available address in the output area (the pointer to the location following 
the last digit stored) 


The $CBOMG routine does not return any error conditions to the caller. 


$CBOMG 


DESCRIPTION 


The $CBOMG routine pushes the predefined conversion parameters on the stack. It then passes 
the conversion parameters in Register 2 to the General Purpose Binary to ASCII Conversion 
Routine ($CBTA), which performs the actual conversion of the binary number. 


The $CBOMG routine calls the $SAVRG routine to save and restore Registers 3 through 6 of the 
calling task, and destroys the contents of Registers 1 and 2. 


EXAMPLE 


The following source statements call the $CBOMG routine to convert a binary number stored in 
the buffer BNUM and store the converted 6-digit ASCII octal magnitude number in the buffer 
OCOUT: 


OCOUT: .BLKB 6 ; OOTPUT BUFFER 
- EVEN 

BNUM: .WORD 162710 
MOV #OCOUT, RO 
MOV BNOM, R1 
MOV #1,R2 


INPUT VALUE | 
PUTS THE STARTING ADDRESS OF THE OUTPUT AREA IN REGIS’ 
PUTS THE BINARY NUMBER TO BE CONVERTED IN REGISTER 1 
PUTS THE VALUE 1 IN REGISTER 2 (SETS THE ZERO 
INDICATOR FLAG TO 1) TO SPECIFY THAT 
LEADING ZEROS ARE NOT TO BE SUPPRESSED 
CALLS THE $CBOMG ROUTINE 


we 20 Yao Se Se YO Ne 


CALL S$CBOMG 
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$CBOSG—Convert binary to signed octal routine 


The $CBOSG routine converts an internally stored binary number to a 6-digit signed ASCIl octal 
number. 


aes 
FORMAT 
CALL $CBOSG 
The $CBOSG routine uses the following predefined conversion parameters: 
Radix = § 


Field width = 6 characters 
Sign flag = SIGNED 


INPUT 


output address 
In Register 0: the starting address of the output area in which the converted 6-digit number will 
be stored 


input number 
In Register 1: the binary number to be converted 


zero suppression indicator 
In Register 2, one of the following values: 


R2 «= 0 to specify suppression of leaciing zeros in the converted number (the output number will be left-justified) 
R2 = £Nonzero to specify no suppression of leading zeros 


OUTPUT 


result ; 
In the specified output area: the converted signed number, a maximum of six digits in length 


next output address 
In Register 0: the next available address in the output area (the pointer to the location following 
the last digit stored) 


The $CBOSG routine does not return error conditions to the caller. 
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DESCRIPTION 


The $CBOSG routine pushes the predefined conversion parameters on the stack. It then passes the 
conversion parameters in Register 2 to the General Purpose Binary to ASCII Conversion Routine 
($CBTA), which performs the actual conversion of the binary number. | 


The $CBOSG routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
calling task, and destroys the contents of Registers 1 and 2. 
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$CBTMG—Convert binary byte to octal magnitude 
routine 


The $CBTMG routine converts an internally stored binary byte to a 3-digit ASCII unsigned octal number. 


FORMAT 


CALL $CBTMG 


The $CBTMG routine uses the following predefined conversion parameters: 
Radix = 8 

Field width = 3 characters 

Sign flag = UNSIGNED 


INPUT 


output address 
In Register 0: the starting address of the output area in which the converted 3-digit number will 
be stored 


input binary byte 
In Register 1 (low-order byte): the binary byte to be converted 


zero suppression indicator 
In Register 2, one of the following values: 


R2 = 0 to specify suppression of leadirig zeros in the converted number (the number will be left-justified) 
R2 «= Nonzero to specify no suppression of leading zeros 


OUTPUT 


result 


In the specified output area: the converted number, a maximum of three digits in length 


next output address 
In Register 0: the next available address in the output area (the pointer to the location following 
the last digit stored 


The $CBTMG routine does not return error conditions to the caller. 
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DESCRIPTION 


The $CBTMG routine pushes the predefined conversion parameters on the stack. It then passes 
the conversion parameters in Register 2 to the General Purpose Binary to ASCII Conversion | 
Routine ($CBTA), which performs the actual conversion of the binary byte. 


The $CBTMG routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
calling task, and destroys the contents of Register 2. In addition, $CBTMG clears the high-order 
byte of Register 1 (the low-order byte is unchanged). 


, 
EXAMPLE | 


| 
The following source statements call the $;CBTMG routine to convert a binary number stored in 
the buffer TBUF and store the converted 3-digit ASCII octal number in the buffer BOUT: 


BOUT: - BLKB 3 ; OUTPUT BUFFER 
«EVEN 

TBUF: - BYTE 177 + INPUT BUFFER 
EVEN 


MOV #BOUT, RO ? ADDRESS OUTPUT BUFFER 

MOVB TBUF, R1 ? GET BINARY CODE 

MOVB #1,R2 7 SPECIFY NO ZERO SUPPRESSION 

CALL SCBIMG # CONVERT THE BINARY NUMBER TO OCTAL 
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$CBTA—General purpose binary to ASCIl 
conversion routine 


The $CBTA routine converts internally stored binary numbers to ASCII decimal or octal numbers when 
called by the binary-to-decimal and binary-to-octal conversion routines. 


EFQRMSCBTA . 
INPUT 
output address 


In Register 0: the starting address of the output area in which the converted ASCII number will 
be stored 


input value 
In Register 1: the binary value to be converted 


conversion parameters 
In Register 2, the following options: 
Bits 0 — 7 (Low byte.) Must contain the conversion radix (2 to 16 decimal). 


Bit 8 Must contain the unsigned flag ( = 0) if unsigned value to be converted: or must contain the sign 
flag ( = 1) if signed value te be converted. 


(The minus sign is not counted in the output field width when you convert a negative signed 
number. The $CBTA routins will use a space in the output buffer for the minus sign.) 


Bit 9 Zero suppression flag = 0; or nonzero suppression flag = 1. 
Bit 10 Blank fill flag = 1 to specity replacement of leading zeros with blanks (only if nonzero suppression 
flag ze 1). 


Blank fill flag = 0 to specify no replacement of leading zeros (if bit 9 = 1). 
(When the zero suppression flag = 0, the blank fill flag is ignored.) 


Bits 11-15 | Must contain a numeric value from 1 to 32 specifying the fleld width. If you convert a negative 
signed number, remember to add a space in the field width for the minus sign. 


OUTPUT 


result 
In the specified output area: the converted number, from 1 to 32 digits in length 


next output address 
In Register 0: the next available address in the output area (the pointer to the location following 
the last digit stored) 


The $CBTA routine does nct return any error conditions to the caller. 


$CBTA 


DESCRIPTION 


The $CBTA routine converts internally stored values according to the user-defined conversion 
parameters, which the calling routine passes as an input argument in Register 2. 


Note that the $CBTA routine does not add an extra space for the minus sign (—) to the predefined 
field-width parameter. If you are converting a negative number, expect that one of the characters 
in the output area will be used for the minus sign. 


The $CBTA routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
caller, and calls the $DIV routine to perform the required division. The $CBTA routine also — 
destroys the contents of Registers 1 and 2. | 


EXAMPLE 


The following source statements set the conversion parameters, expressed in the number 150125, 
which will determine the format of the output by $CBTA. The statements call the $CBTA routine 
to convert a binary value in Register 3 and store the ASCII result in buffer CASTR: 


CASTR: .BLKB a2 ; OUTPUT BUFFER 
- EVEN 
MOV. RO,~(SP) ? SAVE REGS FOR CONVERT CALL 
MOV Rl, -(SP) 
MOV R2,-(SP) 
MOV #CASTR, RO ; ADDRESS TO CONVERT INTO 
MOV R3,R1 + VALUE TO CONVERT 
MOV #15012, R2 7 3-DIGIT, NO ZERO SUPPRESSION 


| 
CALL SCBTA CONVERT BINARY TO ASCII | 
| 


In this example, the binary expression of the value in Register 2 (0001101000001010) sper that 
the output will have the the following conversion parameters: 


Conversion = 1040 

radix 

Sign flag = 0 (unsigned value) | 
NOSUP flag = 1 (no zero suppression) 

Blank fill flag = 0 (no replacement of leading zeros with blanks) 

Field width = 3 
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$C5TA—Radix-50 to ASCII conversion routine 


The $C5TA routine converts an internally stored 16-bit Radix-50 value to an ASCII character string. 


FORMAT 

CALL $C5TA 

INPUT 

output address 

In Register 0: the address that will point to the first byte of the converted string 
Radix-50 word 


In Register i: the Radix-50 value you want to convert 


OUTPUT 


next output address 
In Register 0: the address of the next byte after the last character stored in the output area 


result 
In the specified output area: the converted ASCII 3-character string, stored in a maximum of three 
consecutive bytes 


The $C5TA routine does not return error conditions to the caller. It destroys the contents of 
Registers 1 and 2 and does not use Registers 3 through 5. 


EXAMPLE 


The following source statements call the $C5TA routine to convert a Radix-50 number stored in the 
buffer CRNTS and store the ASCII string result in the buffer SCRPTR: 


CRNTS: .RADSO /GEN/ 7 RADIX VALUE 
SCRPTR: .BLKB 3 ; OUTPUT BUFFER 
- EVEN 
MOV #SCRPTR, RO ; SET OUTPUT BOFFER ADDRESS 
MOV CRNTS, R1 + GET RADIX VALUE 
CALL $CSTA ; CONVERT IT 
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Output Formatting Routines 


The output formatting routines convert internally stored data to external ASCII characters and 
format the converted characters to produce readable output. The five output formatting routines 
are as follows: 


e 


The Uppercase Text Conversion Routine (SCVTUC), which converts lowercase ASCII text to 
uppercase 


The Date String Conversion Routine ($DAT), which converts a 3-word binary date to a 
9-character ASCII output string | 


The Alternate Date String Conversion Routine ($DAT), which converts a date to a user-defined 
ASCII format.up to 25 characters long 


The Time Conversion Routine ($TIM), which converts the binary time to an ASCII output 
string 


The Edit Message Routine (SEDMSG), which converts internally stored data to the 
user-specified type of ASCII data (alphanumeric, octal, decimal) and formats the converted 
data to produce meaningful output for printing or display 


$CVTUC 


$CVTUC—Uppercase text conversion routine 


The $CVTUC routine converts lowercase ASCII text to uppercase. The routine performs a byte-by-byte 
transfer of the input ASCII character string, converting all lowercase alphabetic characters to uppercase, 
and transferring all uppercase characters unchanged to the output string. 


FORMAT 


CALL $CVTUC 


INPUT 


input address 
In Register 0: the address of the text string to be converted 


output address 
In Register 1: the address of the output area for the uppercase string 


number input bytes 
In Register 2: the number of bytes in the string to be converted 


NOTE: The number of bytes cannot be stated as 0. A statement of 0 will cause $CVTUC 
to fail. 


OUTPUT 


result 
In the output area: the converted string 


next input address 
In Register 0: a pointer to the next available wddcoes’ in the input area 


next output address 
In Register 1: a pointer to the next available address in the output area 


DESCRIPTION 


The $CVTUC routine converts all ASCII alphabetic characters in the input string to uppercase. 
Any other characters are moved from the input area to the output area in their sequential 
positions. You can specify the input area address as the output area address (RO = R1) when 
the $CVTUC routine is called. If you specify this at the outset, Register 0 and Register 1 will 
be left pointing to the character following the string. The $CVTUC routine converts lowercase 
alphabetic characters to uppercase where they occur in the input area. The original lowercase 
contents of the input area are destroyed. 


6-2 


SCVTUC 


$CVTUC destroys the contents of Register 2 and does not use Registers 3 through 5 of the calling 
task. | . 


EXAMPLE 


The following source statements call the $CVTUC routine to convert an ASCII string to uppercase: 


MACNAM: .BLKW 3 WORK BUFFER 


MOV #MACNAM, RO POINT TO WORK BUFFER | 
MOV #6, R2 SAVE STRING COUNTER | 
MOV RO, R1 POINT TO OUTPUT ADDRESS 


Se Se Ne Se Be 


CALL $cvTuc DO THE CONVERSION 


(In this example, the converted string will be stored in the buffer MACNAM because RO = Rl.) 
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$DAT—Date string conversion routine 


The $DAT routine converts the 3-word internal binary date to the standard 8- or 9-character ASCII 
output format. $DAT formats the date for output as follows: 


day-month-year 


FORMAT 


CALL $DAT 


INPUT 


output address 
In Register 0: the address of the output area that will store the converted date 


input address 
In Register 1: the address of the 3-word input area that will store the binary date 


date values 
The input area must contain the following values: 


Word 1 = Last two digits of year 
Word2 «= A 2-digit number from 01 to 12 (month of year) 
Word3 = A 2-digit number from 01 to 31 (day of month) 


OUTPUT 
date 


In the output area: the 8- or 9-character date string in the following format: 
dd-mmm-yy 
dd Day (one character for 1 to 9 and two characters for 10 to 31) 


mmm _ Month (first three letters) 
yy Year (last two digits) 


next output address 


In Register 0: the address of the next available location in the output area 


next input address 
In Register 1: the next address (input R1 + 6) of the input area 
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DESCRIPTION 


The $DAT routine uses and might destroy the contents of Register 2. The calling task jRealdl save 
any critical value contained in Register 2 before calling the $DAT routine. 


$DAT calls the $SAVRG routine to save and restore the contents of Registers 3 through 5 of the 


calling task. 


EXAMPLE 


The following source statements call the $DAT routine to convert the binary date stored in buffer 


DATBUF and store the formatted ASCII output in the buffer EDTBUF: 


DATBUF: .WORD 
«WORD 


EDTBUF: .BLKB 


#EDTBUF, RO 
#DATBUF, R1 
SDAT 


Se Se Me Ne 


YEAR 
MONTH 


DAY 
OUTPUT BUFFER 


OUTPUT FROM CONVERSION 
GET INPOT BUFFER 
CONVERT DATE TO STANDARD ASCII FORMAT | 


After execution, the output buffer contains the following information: 


1L-NOV-87 


$DAT 


$DAT—Alternate date string conversion routine 


The Alternate Date Routine (DAT), accessed by the SYSLIB module INTDAS, converts the binary date 
in a format not dependent upon the DIGITAL-standard date format (dd-mmm-yy). The calling sequence 
is the same as for the standard format $DAT routine. 


FORMAT 


CALL $DAT 


INPUT 


output address 


In Register 0: the address of the output area that will store the converted date 


input address 
In Register 1: the address of the 3-word input area that will store the binary date 


date values 
In the input area, the following definitions: 


Word 1 = Last two digits of year 
Word2 «= A 2-digit number from 01 to 12 (month of year) 
Word3 = A 2-digit number from 01 to 31 (day of month) 


OUTPUT 


date 
In the output buffer: the converted and formatted string (up to 25 characters), determined by your 
definitions of the logical names SYS$DATE_FORMAT and SYS$MONTH_non 


next output address 


In Register 0: the address of the next available location in the output area 


next input address 
In Register 1: the next address (input; R1 + 6) of the input area 


DESCRIPTION 


The alternate $DAT routine is contained in the module INTDAS, which has been inserted into 
SYSLIB with entry points deleted. To include the INTDAS module in your task image, you must 
explicitly request it in one of the following ways: 
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Before building the task, invoke the Librarian Utility (LBR) and enter the following command 
line to include the module INTDAS in the task: | 


LB: (1,1]SYSLIB/LB: INTDAS 


Insert the module EDDAT without entry points, and INTDAS with entry points, into SYSLIB 
by entering the following command sequence: 


> LBR 

LBR> EDDAT=LB: {1,1]SYSLIB.OLB/EX:EDDAT 
LBR> INTDAS#LB: (1, 1] SYSLIB.OLB/EX: INTDAS 
LBR> LB: (1,1]SYSLIB.OLB/RP/-EP=EDDAT 
LBR> LB: (1,1]SYSLIB.OLB/RP2INTDAS 

LBR> 

> PIP INTDAS.OBJ;*/DE, EDDAT.OBUd; * 


| 
The alternate $DAT routine’s calling sequence remains the same as for the standard $DAT rouene: 


but the logical name SYS$DATE_FORMAT contains the following character formats: 


Argument Effect | 


DD Print 2-digit day of month with leading zero ! 
zD Print 2-digit day of month with leading zero suppressed 

MM . Print 2-digit month number with leading zero 

ZM Print 2-digit month number with leading zero suppressed 

YY Print 2-digit year with leading zero 

ZY Print 2-digit year with leading zero suppressed 

MMM Print alphabetic month (not necessarily three characters long) 


You can use additional characters (other than the uppercase letters D, Z, M, and Y) in 

SYS$DATE_FORMAT as delimiters. If SYS$DATE_FORMAT is not defined, you get the | 
DIGITAL-standard date format (dd-mmm-yy) by default. SYS$DATE_FORMAT can have a | 
maximum length of 16 characters. | 


The logical SYSSMONTH_nn (where nn is 01 to 12) provides the alphabetic month to be | 
printed when the mmm attribute is used. If SYS$MONTH_nn is not defined, you get the _ 
DIGITAL-standard 3-letter month abbreviations (mmm) by default. SYS$MONTH_nn can have a 
maximum length of 12 characters. 


Logical translation is done in standard order. A local terminal assignment can override a_ 
system- -wide assignment, which permits the same program to produce output in the individual 
user's own language or preferred format. 


There are two limitations to the alternate date routine. First, using it necessitates more output 
buffer space than the traditional format because the output produced can be as long as 25 
characters. The standard $DAT routine, however, produces eight or nine characters. Second, the 
new module can be linked with many, but not all, existing programs. An example of a program ‘that 
cannot use this routine is one that performs operations on the resulting output string, expecting it 
to be in the format produced by the standard routine. 


The INTDAS module contains the routines $DAT and $TIM. The $TIM routine has not been | 
modified; it produces the standard time format, as described in Time Conversion Routine ($TIM). 


The $DAT routine uses and might destroy the contents of Register 2. The calling task should save 
any critical value contained in Register 2 before calling the $DAT routine. 


$DAT 


$DAT calls the $SAVRG routine to save and restore the contents of Registers 3 through 65 of the 
calling task. 


EXAMPLE 


Assume that you have replaced the SYSLIB module INTDAS into your library with entry points 
and are ready to run a program that calls the $DAT routine. Your definition, at the system prompt, 
of the logical names SYS$DATE_FORMAT and SYS$MONTH_nn will determine the output of the 
$DAT routine when it executes, as shown in the following examples: 


DEFINE SYSSDATE_FORMAT = "MMM 72D, 19YY" 
DEFINE SYSSMONTH_11 = "November" 
Output: November 1,1987 
DEFINE SYSSDATE_FORMAT = “DD.MMM.YY" 
DEFINE SYSSMONTH_11 = "XI" 
Output: 01.XI.87 


SYSSDATE_FORMAT = "2D/MM/YY" 
Output: 1/11/87 
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$TIM—Time conversion routine 


The $TIM routine converts the binary time, in a standard format, to an ASCII output string in the form: 
HH:MM:SS.S 
The $TIM routine converts and formats the time for output in one of the following forms: 


hour 

hour:minute 
hour:minute:second 
hour:minute:second. fraction 


ae 
ee 
. 


FORMAT 


CALL $TIM 


INPUT 


The standard format for $TIM input values is shown in the following table: 


Output — . | 
Word Significance Format Value Range | 
WD1 —Hour-of-Day HH 0 to 23 | 
WD2 _—s— Minute-of-Hour MM 0 to 59 | 
WD3 Second-of-Minute ss 0 to 59 
wO04 Tick-of-Second S Depends on clock frequency : 
WwDS5 Ticks-per-Second Ss Depends on clock frequency 
output address 
In Register 0: the address of the output area that will store the converted time . 
input address | 
In Register 1: the starting address of the input area that stores the time values 
parameter count 


In Register 2, the parameter count, where: 
R2 = Oor 1, to specify that the hour (word 1) is to be converted in the format HH 


R2 = 2, to specify that the hour and minute (words 1 and 2) are to be converted in the format HH:MM 


R2 = _ 3, to specify that the hour, minute, and second (words 1, 2, and 3) are to be converted in the format 
HH:MM:SS 


R2 «= 4or 5, to specify that the hour, minute, second, and tick are to be converted in the format HH: ‘MM: S$S.S 
(where .S = tenth of second) 


NOTE: For HH, the $TIM routine always returns two characters for all values specified. 
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STIM 


OUTPUT 
next output address 


In Register 0: the address of the next available location in the output area 


next input address 
In Register 1: the address of the next word in the input area 


time string 


In the specified output area: the converted time string 


DESCRIPTION 


The $TIM routine calls the $SAVRC routine to preserve Registers 3 through 5 of the calling task. 
The contents of Registers 0 and 1 are updated and returned to the calling task. The $TIM routine 
destroys the contents of Register 2 (the parameter count). It also calls the following routines: 


¢ The $DIV routine, which performs the division required to convert binary values to ASCII 
format 


¢ The $CBDAT routine, which actually performs the time conversion, two digits at a time 


The $TIM routine does not check the validity of the input data. 


EXAMPLE 


The following source statements call the $DAT and $TIM routines to convert time values to the 
standard formats: 


Assume a program contains an input block, an output block, and source statements. For example: 


BDBLK: ~WORD 987. ; YEAR 
WORD 11 ; MONTH 
WORD O1 ; DAY 
WORD 10 3; HOUR 
«WORD 15 3; MINUTES 
WORD 35 ; SECONDS 
WORD xx 
-WORD <x 
DTBLK: -BLKB 20. ; 
MOV #DTBLK, RO >; PUTS ADDRESS OF OUTPIT AREA IN REGISTER 0 
MOV #BDBLK, R1 ; PUTS ADDRESS OF INPUT BINARY DATE AREA IN REGISTER . 
CALL SDAT ; CALLS THE SDAT ROUTINE 


MOVB #11, (RO)+ ; PUTS TAB AFTER DATE IN OUTPUT BUFFER 

; REGISTER 0 NOW CONTAINS NEXT ADDRESS IN DTBLK FR 
; REGISTER 1 NOW CONTAINS ADDRESS OF NEXT WORD 
; HOUR 10) IN BDBLK FROM SDAT 
+ SPECIFIES THE HH:MM:SS FORMAT FOR CONVERTED TIME 


CALLS THE STIM ROUTINE 


MOV #3.,R2 
CALL STIM 


After execution, the output buffer will contain the following information: 
1-NOV-87 10:15:35 
The time and date fields are left-justified. 
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S$EDMSG—Edit message routine 


The $EDMSG routine converts internally stored data to ASCII decimal, octal, or alphanumeric 
characters, and controls the layout of the converted characters. You can use the $EDMSG routine 
to produce printed or displayed text in meaningful, readable formats. | 


FORMAT 


CALL $EDMSG 


INPUT 


output address | 
In Register 0: the starting address of the output block | 


input address 
In Register 1: the address of the input string 


argument block address : 
In Register 2: the starting address of the argument block | 


| 
inpu t str. ing | 
The input string contains the editing directives and ASCII text that determine data conversion and 
format control for the $EDMSG routine. The directives must be in one of the following formats: 


¢ %} 
¢ %nl 
* VI 


The directives have the following effects: 


Directive Effect 
% A delimiter that identifies an editing directive to the SEDMSG routine. 
n An optional repeat count (decimal number) specifying the number of times the editing operation 


is to be repeated by the SEDMSG routine. If n = 0 or is not specified, a repeat count of 1 is 
assumed. 


< 


Specifies that the repeat count is a value in the next word in the task’s argument block. If the 
value is 0, a repeat count of 1 is assumed. 


An aiphabetic letter specifying one of the editing operations to be performed by the SEDMSG 
routine, as shown in Table 6-1. 


Input strings can contain ASCII text as well as editing directives. Any number of dixeddgesvd can 
appear in an input string. Input strings must be in ASCIZ format: 


$EDMSG 


argument block (ARGBLK) 


The argument block contains the binary data to be converted, the addresses of ASCII and extended 
ASCII characters, or the address of a double-precision value. 


Prior to calling the $EDMSG routine, set up the appropriate argument block, as follows: 


* For $EDMSG to move ASCII or extended ASCII characters to the output block, the argument 
block must contain the address of the ASCII characters. 


* For $EDMSG to convert a binary byte to octal format, the argument block must contain the 
address of the binary byte. 


* For $EDMSG to convert binary values, the argument block must contain the values. 


* For $EDMSG to perform filename string conversion, the argument block must contain the 
following information: 


Word 1 = Radix-50 file name 
Word 2 = Radix-50 file name 
Word3 =  Radix-50 file name 
Word 4 = Radix-50 file type 
Word 5 «= _ Binary version number 
* For $EDMSG to convert a binary date, the argument block must contain the following 
information: 
Word 1 = Year (last two digits) 
Word 2 = Number (01 to 12) of month 
Word 3. = Day of month (01 to 31) 


NOTE: $EDMSG does not check the validity of the date values. If you specify 
erroneous date values, output results will be unpredictable. 


* For $EDMSG to convert binary time, the argument block must contain the following 
information: 


Word 1 = _ ~ Hour-of-day (0 to 23) 

Word 2 «= Minute-of-hour (0 to 59) 

Word3 «= Second-of-minute (0 to £9) 

Word 4 «= _ Tick-of-second (depends on clock frequency) 
Word 5 = Ticks-per-second (depends on clock frequency) 


output biock (OUTBLK) 
The output block in which $EDMSG is to store output 


OUTPUT 
converted data 
In the output block: the converted/formatted data 


next byte 
In Register 0: the address of the next available byte in the output block (the $EDMSG routine 
clears this byte to provide a null-terminated (ASCIZ) string) 
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output length | 
In Register 1: the number of bytes transferred to the output block (the count does not include the 
null-terminating byte) 


next argument address | 
In Register 2: the address of the next argument in the argument block | 


Table 6—1 describes the editing directives for the $£DMSG routine. 


Table 6-1 $EDMSG Routine Editing Directives 
Directive Form Operation 


A (ASCIl' string) YoA Move the ASCII character from address in ARGBLK to OUTBLK. 
%nNA Move the next n ASCIl characters from address in ARGBLK to OUTBLK; 


%VA Use the value in the next word in ARGBLK as repeat count and move the 
specified number of ASCIl characters from address in ARGBLK to OUTBLK. 


B (binary byte to %B Convert the next binary byte from address in ARGBLK to unsigned Scat number 
octal conversion) and store resuit in OUTBLK. 


%nB Convert the next n binary bytes from address in ARGBLK to octal numbers and 
store resuits in OUTBLK; insert space between numbers. 


%VB Use the value in the next word in ARG&LK as the repeat count. convert! ithe 
specified number of binary bytes from address in ARGBLK to octal numbers, and 
store results in OUTBLK; insert space between numbers. | 


D (binary to signed %D Convert the binary value in the next word in ARGBLK to signed decimal: and 
decimal conversion, 0 store result in OUTBLK. 
suppress) 


%nD Convert the next n binary values in ARGBLK to signed decimal and store 
results in OUTBLK; insert tab between numbers. 


%VD Use the value in the next word in ARGBLK as repeat count, convert the specified 
number of binary values to signed decimal, and store results in OUTBLK} insert 
tab between numbers. 


E (extended %E Move the extended ASCII character from the address in ARGBLK to thq 


ASCII") OUTBLK. | 


%nE Move n extended ASCI! characters from the address in ARGBLK to OUTBLK. 


%VE Use the value in the next word in ARGBLK as repeat count and move the 
specified number of ASCII characters from the address in ARGBLK to oe 


F (form feed) Yor Insert a form-feed character in OUTBLK. 
NF Insert n form-feed characters in OUTBLK. 


%VF Use the value in the next word in ARGBLK as repeat count and insert specified 
number of form-feed characters in OUTBLK. | 


I (include ASCIZ ol Use the next value in ARGBLK as the address of an ASCIZ string to be logically 
string) included in the format string at this point. | 


‘Extended ASCII characters consist of the printable characters in the 7-bit ASCII code. If nonprintable characters 
appear in an ASCIl input string, the E directive replaces them with a space, while the A directive transfers the 
nonprintable characters to the output block. 
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Table 6-1 (Cont.) SEDMSG Routine Editing Directives 


Directive Form 
M (binary to %M 
decimal magnitude 
conversion, 
O suppress) 
%nM 
%V'M 
N (new line- %N 
carriage returrv 
line feed) YrnN 
NN 
O (binary to %O 
signed octal 
conversion) 
%nO® 
%YN'O 
P (binary to MP 
unsigned octal 
magnitude 
conversion, 
no 0 suppress) %enP 
%\'P 
Q (binary to %Q 
octal 
magnitude 
conversion, 
0 suppress) %nQ 
YQ 
R (Radix-50 %Ft 
to ASCIl) 
%nR 
*VR 
S (space) %S 
%nS 
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Operation 


Convert the binary value in the next word in ARGBLK to decimal magnitude with 
leading zeros suppressed and store the result in OUTBLK. 


Convert the next n binary values in ARGBLK to decimal magnitude with leading 
zeros suppressed and store the results in OUTBLK; insert tab between numbers. 


Use thie value in the next word in ARGBLK as repeat count, convert the specified 
number of binary values to decimal magnitude with leading zeros suppressed, 
and store the results in OUTBLK; insert tab between numbers. 


Insert CR and LF characters in OUTBLK. 


Insert n CR and LF characters in OUTBLK. 


Use the value in the next word in ARGBLK as repeat count and insert the 
specified number of CR and LF characters in OUTBLK. 


Convert the binary value in the next word in ARGBLK to signed octal and store 
the result in OUTBLK. 


Convert the next n binary vaiues in ARGBLK to signed octai and store the 
results in OUTBLK; insert tab between numbers. 


Use the value in the next word in ARGBLK as repeat count, convert the specified 
number of binary values to signed octal, and store the results in OUTBLK; insert 
tab between numbers. 


Convert the binary value in the next word in ARGBLK to octal magnitude with no 
leading zeros suppressed and store the result in OUTBLK. 


Convert the next n binary values in ARGBLK to octal magnitude with no leading 
zeros suppressed and store the results in OUTBLK; insert tab between numbers. 


Use the value in the next word in ARGBLK as repeat count, convert the specified 
number of binary values to octal magnitude with no leading zeros suppressed, 
and store the resuits in OUTBLK; insert tab between numbers. 


Convert the binary value in the next word in ARGBLK to octal magnitude with 
leading zeros suppressed and store the result in OUTBLK. 


Convert the next n binary values in ARGBLK to octal magnitude with leading 
zeros suppressed and store the results in OUTBLK; insert tab between numbers. 


Use the value in the next word in ARGBLK as repeat count, convert the soecified 
number of binary values to octal magnitude with leading zeros suppressed, and 
store the results in OUTBLK; insert tab between numbers. 


Convert the Radix-50 value in the next word in ARGBLK to ASC!! and store the 
result in OUTBLK. 


Convert the next n Radix-50 values in ARGBLK to ASCII and store the results in 
OUTBLK. 


Use the value in the next word in ARGBLK as repeat count, convert the specified 
number of Radix-50 values to ASCII, and store the results in OUTBLK. 


Insert a space in OUTBLK. 
Insert n spaces in OUTBLK. 


SEDMSG 


Table 6-1 (Cont.) $EDMSG Routine Editing Directives 


Directive Form Operation 

%VS Use the value in the next word in ARGBLK as repeat count and insert the 
specified number of spaces in OUTBLK. 

T (double- %aT Convert the double-precision unsigned binary value at the address in ARGBLK 

precision binary to decimal and store result in OUTBLK. 

to decimal 

conversion) %nT Convert the next n double-pracision binary values starting at the address in 
ARGBLK to decimal and store results in OUTBLK; insert tab between numbers. 

%VT Use the value in the next word in ARGBLK as repeat count, convert the specified 
number of double-precision binary values starting at the address in ARGBLK to 
decimal, and store the results in OUTBLK; insert tab between numbers. 

U (binary to %U Convert the binary value in ARGBLK to decimal magnitude with no leading zeros 

decimal magnitude suppressed and store result in OUTBLK. | 

conversion, | 

no 0 suppress) %nU Convert the next n binary values in ARGBLK to decimal magnitude with no 
leading zeros suppressed and store results in OUTBLK; insert tab between 
numbers. 

%VU Use the value in the next word in ARGBLK as repeat count, convert the ae 
number of binary values to decimal magnitude with no leading zeros Sena 
and store resuits in OUTBLK; insert tab between numbers. 

X (filename %X Convert Radix-50 filename string in ARGBLK to ASCIl string in format name. typ; 
string conversion) convert octal version number, if present, to ASCIl and store results in OUTBLK. 
Convert next n Radix-50 filename strings in ARGBLK to ASCII strings in format 

%nX  name.typ; convert octal version numbers, if present, to ASCII and store results in 
OUTBLK; insert tab between strings. | 

%VX Use the value in the next word in ARGBLK as repeat count, convert specified 
number of Radix-50 filename strings to ASCII strings in format name.typ; convert 
octal version numbers, if present, to ASCII and store resuits in OUTBLK; pepe 
tab between strings. 

Y (date %Y Convert the next three binary words in ARGBLK to ASCII date in format. 

conversion) dd-mmm-yy and store in OUTBLK. For this directive, a repeat is acceptable 
but will be ignored. 

Z (binary time %0Z Convert binary hour-of-day in the next word of ARGBLK to ASCIl. and store in 

conversion) or OUTBLK in format HH. | 

%1Z | 
Convert the binary hour-of-day and minute-of-hour in the next two words of 

%2Z ARGBLK to ASCII and store in OUTBLK in format HH:MM. ! 

%o3Z Convert the binary hour-of-day, minute-of-hour, and second-of-minute in the next 
three words of ARGBLK to ASCII and store in OUTBLK in format HH:MM:SS. 

AZ Convert the binary hour-of-day, minute-of-hour, second-of-minute, and | 

or ticks-of-second or ticks-per-second in the next five words of ARGBLK to ASCII 

%5Z and store in OUTBLK in format HH:MM:SS.S, where .S = tenth of second. 

< (define <stack>byte %n< Insert n ASCII spaces followed by a field mark (NUL) in OUTBLK to define a 
field) fixed-length byte field. The output pointer will point to the first space. 

> (locate %n> Increment the OUTBLK pointer until a field mark (NUL) is located or the n: repeat 
field mark) count is exceeded. 


DESCRIPTION 
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The $EDMSG routine converts internally formatted data, in an argument block, to external format 
and stores it in the calling task’s output block. The editing performed by the $EDMSG routine is 
specified by user directives within an input string. Any nonediting directive characters are simply 
copied into the output block. Output strings are in ASCIZ format. 


The $EDMSG routine calls the output data conversion routines (also described in Chapter 5) to 
convert binary data to the specified external format. See the detailed descriptions of individual 
conversion routines for specific output formats. 


The $EDMSG routine scans the input string, character-by-character. If it encounters nondirective 
(or “unknown” directive) characters, it transmits them directly to the task’s output block. When 
the $EDMSG routine finds a percent sign ( % ) delimiter, it interprets the character(s) following the 
delimiter. [f it encounters a data conversion directive, the SEDMSG routine accesses the argument 
block, converts the specified data, and transmits it to the output block. If a format control directive 
is encountered, the routine generates the specified control(s) and transmits the data to the output 
block. If the percent sign delimiter is not followed by a valid operator, or if multiple delimiters 
are found, the $EDMSG routine transmits the first delimiter (and any subsequent delimiters not 
followed by a valid directive character) to the output block. 


NOTE: You can call an appropriate output routine to output the converted/formatted 
data. 


$EDMSG calls the $SAVRG routine to save and restore Registers 3 through 5 of the calling task. 


EXAMPLE 


1 The following source statements call the $£DMSG routine to format the data stored in 
ARGBLK, as specified by the directives in buffer ISTRING: 


START: MOV #OUTBLK, RO 
MOV #ISTRING, R1 
MOV #ARGBLK, R2 

CALL SEDMSG 


; SET UP ADDRESS OF INPUT 
; SET OUP ARGUMENT BLOCK 
; DO THE FORMATTING 


ISTRING: -ASCIZ /%F%12S***TEXT* ** 43N$8S4VDE2NE125** *END**** / 
-EVEN 
ARGBLK: «WORD 3. 7 NUMBER OF VALUES TO CONVERT 
eWORD 99. 7 VALUES 
«WORD -37. ; TO 
-WORD 137. ; FORMAT 
OUTBLK: -BLKB 100. 7 OUTPUT BLOCK 
; SET UP ADDRESS OF OUTPUT 


The editing directives shown in this example have the following effects: 


Directive Effect 
%F Insert a forrn feed in OUTBLK (start a new page). 
—%128 Insert 12 spaces in OUTBLK and move the ASCIl string to OUTBLK (indent the first line 12 
spaces and insert the header ***TEXT’**). 
%3N Insert three pairs of CR-LF characters in OUTBLK (generate two blank lines). 
%8S Insert eight spaces in CUTBLK (indent the next line eight spaces). 
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Directive Effect 


%VD Use the first vaiue (3) in ARGBLK as the repeat count and convert the next three binary values 
in ARGBLK to signed decimal; store each value, followed by a tab, in OUTBLK (output three 
signed decimal numbers set up in columns). 


%2N Insert two pairs of CR-LF characters In OUTBLK (generate one blank line). 


%12S __iInsert 12 spaces at the beginning of a line in OUTBLK and move the ASCII string to OUT: BLK 
(indent 12 spaces and insert the text ***END****). ; 


The example produces the following output: 
www TEXT wee 
99 -37 137 


eX END * 8 ee 


The following example calls the $£DMSG routine to convert the data stored in IBLK, as 
specified by the formatting directives in the buffer INSTR: 


INSTR: -ASCIZ /%F%5S***F, TREVISANI WORK REPORT FROM %Y TO %Y¥***/ 


- EVEN 
IBLK: »WORD 87. + YEAR 

eWORD 8. ; 8TH MONTH (AUG) 

eWORD 22. 7 DAY 

»WORD 87. ; YEAR 

«WORD 9. ; 9TH MONTH (SEP) 

-WORD 16. 7 DAY 
PRBLK: -BLKB 100. 7; OUTPUT BLOCK 
BEGIN: MOV #PRBLK, RO SET UP ADDRESS OF OUTPUT | 


MOV #INSTR,R1 ; SET UP ADDRESS OF INPUT 
MOV #IBLK, R2 7 SET UP ARGUMENT BLOCK 
CALL SEDMSG 3 DO THE CONVERSION 


The editing directives in the example have the following effects: 


Directive Effect 

YF Insert a form feed in PRBLK (start a new page). 

%*%5S Insert five spaces in PRBLK and move ASCIl string to PRBLK (indent the line five spaces ond 
output the header °**F. TREVISAN! WORK REPORT FROM ). | 

YY Convert the next three words in IBLK to formatted date and store in PRBLK followed by ASCII 
text (insert 22-AUG-89 TO in header line). 

%Y Convert next three words in IBLK to formatted date and store in PRBLK followed by Ascll text 


(insert 16-SEP-89°** in header line). 


The above example produces the following output: 


***P, TREVISANI WORK REPORT FROM 22-AUG-89 TO 16-SEP-89*** 


Dynamic Memory Management Routines 


The dynamic memory management routines enable manual management of the space in a task’s 
free dynamic memory. The free dynamic memory consists of all memory extending from the 
assembled code of the task to the highest virtual address owned by the task, excluding resident 
libraries. | 


Initially, these routines allocate free dynamic memory as one large block, from the highest available 
memory address downward. Subsequent memory block allocations are made within the availabie 
memory blocks. Available memory blocks are maintained as a linked list of blocks in ascending 
ee pointed to by a 2-word listhead. Each free memory block contains a 2-word control field, 
where: 


¢ The first word contains the address of the next available block, or 0 if there is not {nother 
block | 


e The second word contains the size of the current block | 


Memory allocation is either on a first-fit or best-fit basis. Allocation is always made from the top 
of the selected available dynamic memory block. The second word of the block is adjusted to reflect 
the new size of the current block of available dynamic memory. As memory blocks are allocates 
completely, they are removed from the free memory list. 


When memory blocks are deallocated (released), they are returned to the free memory list. The 
released memory blocks are relinked to the free memory list in ascending address order. If possible, 
released memory blocks are merged with adjacent memory blocks to form a single, large block of 
free dynamic memory. 


The following three routines perform dynamic memory management functions: 


¢ Initialize Dynamic Memory Routine ($INIDM), which initializes the task’s free dyndmnie 
memory 


¢ Request Core Block Routine ($RQCB), which allocates blocks of memory in the free panne 
memory 


¢ Release Core Block Routine ($RLCB), which releases (deallocates) previously allocated memory 
blocks in the executing task’s free dynamic memory 


To use the dynamic memory management routines, provide the following information in ithe source 
program: | 


¢ A 2-word free memory listhead in the following format: 
FREEHD: .BLKW 2 


¢ The appropriate call and argument(s) for the given routine. 


Before building the task, invoke the Librarian Utility (LBR) and enter the following command line 
to include the modules INIDM and EXTSK in the task: 


LB: [1,1] VMLIB/LB: INIDM: EXTSK 
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SINIDM—Initialize dynamic memory routine 


The $INIDM routine establishes the initial state of the free dynamic memory available to the executing 
task. The free dynamic memory consists of all memory extending from the end of the task code to the 
highest virtual address usecl by the task, excluding resident libraries. 


FORMAT 


CALL $INIDM 


INPUT 


free memory listhead 


In the program's data section: a 2-word memory listhead 


free memory listhead address 
In Register 0: the address of the free memory listhead 


OUTPUT 


first address 
In Register 0: the first address in the task 


last address 


In Register 1: the address following the task image (last available address in the free dynamic 
memory) 


memory size 
In Register 2: the size of the free dynamic memory 


DESCRIPTION 


The $INIDM routine performs the following actions: 

¢ Rounds the free dynarnic memory base address to the next 4-byte boundary 
¢ Initializes the free dynamic memory as a single large block of memory 

¢ Computes the total size of the free dynamic memory 

¢ Sets the outputs in Registers 0 and 1 and returns to the calling task 


Registers 3 through 5 are not used. 


SINIDM 


After initializing dynamic memory, your task can cal] the Request Core Block Routine ($RQCB) to 
allocate memory blocks in the dynamic memory and the Release Core Block Routine ($RLCB) to 
release the allocated blocks. 


eee 
EXAMPLE 


The following source statements call the $INIDM routine to initialize a block of free dynamic : 


memory and save the first address of the task in Register 0: | 


$FREEHD: : .BLEW 2 ; FREE MEMORY LISTHEAD 
MOV #$FREEHD, RO ; SET ARG FOR FREE MEM HEAD | 
CALL § $INIDM ; INITIALIZE MEMORY | 
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$RQCB—Reauest core block routine 


The $RQCB system library routine determines whether there is enough space available in the free 
dynamic memory to satisfy an executing task’s memory allocation request. If memory is available, the 
$RQCB routine allocates the requested memory block. 


FORMAT 
CALL $RQCB 
INPUT 


free memory listhead address 
In Register 0: the address of the free memory listhead 


block size 
In Register 1: the size (nurnber of bytes) of the memory block to be allocated, where: 


Ri «= A value greater than or equal to 0, to specify best-fit allocation 
R1 = A value less than 0, to specify first-fit allocation (the value is negated to determine block size) 


OUTPUT 


block address 
In Register 0: the dynamic memory address of the allocated block 


block size 
In Register 1: the actual size of the allocated block (requested size rounded to next 2-word 
boundary) 


Condition Code 
C bit = Clear if allocation is successful 


(@ bit = Set if allocation is not successful 


The $RQCB routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
calling task. Register 2 is destroyed. 


EXAMPLE 


The following source statements call the $RQCB routine to allocate a block of dynamic memory 
and store the memory address in Register 0: 


74 


SFREEHD:: 


MOV 
MOV 
NEG 
CALL 


-BLKW 2 


#SFREEHD, RO 
#512.,R1 

R1 

SRQCB 


ve Ye Ne 


ze 


FREE MEMORY LISTHEAD 


GET ADDRESS OF FREE CORE POOL 
SIZE OF BLOCK TO BE ALLOCATED 
NEGATE TO SPECIFY FIRST FIT 
REQUEST CORE BLOCK 
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$RLCB—Release core block routine 


The $RLCB system library routine releases a block of previously allocated dynamic memory to the 
free memory list. The memory addresses determine the order of the memory list. 


FORMAT 
CALL $RLCB 
INPUT 


free memory listhead address 
In Register 0: the address of the free memory listhead 


biock size 
In Register 1: the size (number of bytes) of the block to be released 


output address | 
In Register 2: the memory address of the block to be released 


OUTPUT 


released block 


In the free memory list: the released dynamic memory block 


DESCRIPTION 


The $RLCB routine searches the free memory list until it finds the proper address slot and then 
merges the released block into the list. If possible, the released memory block is merged with 
adjacent blocks already in the free rnemory list. 


The $RLCB routine calls the $SAVRG routine to save and subsequently restore Registers 3 
through 5 of the calling task. Register 0 is unchanged, while the contents of Registers 1 and 2 
are destroyed. 


EXAMPLE 


The following source statements call the $RLCB routine to release a block of memory, stored in 
buffer FREEHD, to the free memory listhead: 
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FREEHD:: .BLKW 
REFHD: » WORD 


MOV 
MOV 
MOV 
CALL 


2 
0 


REFHD, R2 
#4,R1 
#FREEHD, RO 
$RLCB 


=e Ne 


Se 30 Ys fe 


FREE MEMORY LISTHEAD 
REFERENCE LISTHEAD 


GET ADDRESS OF ENTRY 
GET SIZE OF ENTRY 

SET ADDRESS OF LISTHEAD 
RELEASE CORE BLOCK 
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Virtual Memory Management Routines 


The virtual memory management routines perform memory allocation and deallocation by paging 
to and from disk file storage to accommodate tasks that require more memory than that available 
in the task’s free dynamic memory at any given time. That is, the routines allow you to bring 
pages into memory when they are needed, hold them there until they are no longer needed, swap 
the pages out, and reallocate their memory space to other pages. These routines do not require the 
memory management hardware and are not related to memory management directives. | 


The virtual memory management routines perform the following major functions: 
¢ Virtual memory initialization 

¢ Dynamic memory allocation 

¢ Virtual memory allocation 


¢ Page management 


Although you can call the individual virtual memory management routines, it is more efficient to 
use them as automatic control systems by calling only the following key routines: 


¢ The Initialize Virtual Memory Routine ($INIVM), which initializes the task’s dpaainie memory 
and the disk work file | 


¢ The virtual memory allocation routines Allocate Virtual Memory Routine ($ALVRT) and 
Allocate Small Virtual Block Routine (SALSVB), which manage the allocation of ah and 


small page blocks to enable page swapping to and from dynamic memory | 
| 
¢ The following page management routines: | 


— The Convert and Lock Page Routine ($CVLOK), which converts a virtual address to a 
dynamic memory address and sets a lock byte in the memory page to prevent its, Pome 
swapped out of memory until it is no longer needed 


— The Unlock Page Routine (SUNLPG), which clears the lock byte in a memory-resifient page 
so that it can be released and its memory space reallocated to another page | 


— The Convert Virtual to Real Address Routine ($CVRL), which converts a virtual address to 
a dynamic memory address 


— The Write-Marked Page Routine (SWRMPG), which sets the “written into” flag of a 
pages | 


Using the Virtual Memory Management Routines 


To call the virtual memory management routines, provide the appropriate call arguments and 
statements in the source program. 


Your task should contain an error-handling routine and symbolic error codes. 


At task-build time, specify the file and the virtual memory management modules ‘eguiben by the 
task. ; | 
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User Error—Handling Requirements 


Four virtual memory management routines detect fatal error conditions. These routines require a 
user-written error-handling routine, entitled $iERMSG. In conjunction with the $ERMSG routine, 
you should include definitions of three global error codes and one global severity code in the task. 
The symbolic error codes are as follows: 


Global Error 
ESR4 Used by the $ALBLKC routine when there is no dynamic memory available for allocation 


ESA73 Used by the $RDPAG and SWRPAG routines when a work file I/O error occurs during an attempt to 
swap pages between resident memory and disk storage 


ESR76 Used by the S$ALVRT routine when there is no virtual storage available for allocation 


S$v2 (Severity code) Used by the four routines cited above to denote a fatal error that must be corrected 
before task execution can resume 


When a fatal error occurs, the detecting routine sets up the following input arguments: 


Register 1 = Low byte: error code 
High byte: severity code (always S$V2) 


Register 2 =» Argument block address 
and issues the following call: 
CALL SERMSG 


Note that most of the virtual memory management routines interact, directly or indirectly, with 
one of the four routines that call $ERMSG (see the General Block Diagram for each routine). The 
only exceptions, which do not result in a call to $ERMSG, are the following routines: 


$EXTSK 
$FNDPG 
$SWRMPG 
$LCKPG 
SUNLPG 


These five routines indicate error conditions by setting the Condition Code C bit. Your 
error-handling operations for these routines should respond to the Condition Code C bit. However, 
these routines might have to link with the error routine $ERMSG. Therefore, you must define 
the global symbols and an $ERMSG routine in your task whenever you use a virtual memory 
management routine. If you have not defined the error-handling routine within the task, the 
undefined global symbol diagnostic message will be generated at task-build time. 


A typical error-handling routine would print a message to indicate the specific error condition, 
close all files (including the work file), and exit. 


Example 


The following source statements illustrate a user-written error-handling routine that can be called 
by a virtual memory management routine: 
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ER60: -ASCI2Z <15>/ACNT--Workfile - dynamic memory exhausted/ 


ER61: -ASCIZ <15>/ACNT--Workfile - IO error or ADDR past EOF/ 
FILOPN: .BYTE 0 ; FILE OPEN FLAG. 0 = NO, 1 = YES 
. EVEN | 
GENFLG: .WORD 0 ; GENERAL FLAG WORD 
, 1 BIT 0 - VIRTUAL FILE OPEN. 1 = OPEN, 0 = CLOSED 
3 2 BIT 1 -. ALLOCATE VIRTUAL BLOCK ERROR FLAG, 1 = ERROR | 
SERMSG:: BIS #2, GENFLG ; SET ALLOCATE BLOCK ERROR | 
CMPB #ESR4,R1 ; DYNAMIC MEMORY ERROR? | 
BNE ERM2 ; NO 
MOV #ER60, RO + YES, GET MESSAGE | 
BR ERROR 
ERM2: CMPB #ESR73,R1 ; I/O BRROR OR ADDRESS PAST EOF? 
BNE ERM3 7 NO 
MOV #ER61,RO ; YES, GET MESSAGE 
BR ERROR | 
ERM3: ; ERROR-HANDLING ROUTINE 
EXIT: TSTB FILOPN .? IS ACCOUNT FILE OPEN? | 
BLE 10$ 7 NO | 
CALL CLOSE ; ROUTINE TO CLOSE ACCOUNT FILE | 
10$: BIT #1, GENFLG ; WORK FILE OPEN? | 
BEQ 15$ ; 7 NO 
CALL CLOSEV ; ROUTINE TO CLOSE VIRTUAL FILE | 
158: 
ERROR: ; ERROR MESSAGE OUTPUT ROUTINE 


NOTE: Generally, the error-handling routine should not attempt to return to the virtual 
memory management routine that detected the fatal error because no meaningful output 
would result. 


Task-Building Requirements : 


There are two versions of the virtual memory management routines: the statistical version and 
the nonstatistical version. Each version consists of 12 program modules, each containing one pr 
more routines, and a data storage module. Individual routines in the virtual memory management 
routines library can reference other routines. The relationship of the modules and routines in the 
library is shown in Table 8—1. | 


Table 8-1 Contents of the Virtual Memory Management Library File 


Moduie Name 


Routine | 
Statistical Nonstatistical Name Routines Referenced | 
ALBLK ALBLK $ALBLK $S$GTCOR, $EXTSK, $WRPAG 
ALSVB ALSVB $ALSVB $ALVRT, SWRMPG, $CVRL, $ALBLK, $ROVCB, SFNDPG, 
$RDPAG | 
CVRS CVRL $CVRL $FNDPG, $ALBLK, $RDPAG | 
EXTSK EXTSK $SEXTSK (none) 
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Table 8-1 (Cont.) Contents of the Virtual Memory Management Library File 


Module Name 


Routine 
Statistical Nonstatistical Name Routines Referenced 
FNDPG FNDPG $FNDPG (none) 
GTCOS GTCOR $GTCOFI $SEXTSK,'SWRPAG 
INIDM? INIDM? SINIDM SEXTSK 
INIVS INIVM SINIVM $ALBLK. SGTCOR, SEXTSK, SWRPAG 
MRKPG MRKPG $LCKPG $FNDPG 
$UNLPG $FNDPG 
S$WRMPIS $FNDPG 
RDPAS RDPAG $RDPAG (none) 
$WRPAG 
ROQVC8 RQVC8 $ROVCS (none) 
VMUTL VMUTL $CVLOK $CVRL, $LCKPG, $FNDPG, $ALBLK, SRDPAG 
VMDAS VMDAT Global data storage module 


'The Extend Task Routine (SEXTSK) is cailed by the $SGTCOR routine, but only if GTCOS, the statistical version of 
$GTCOR, has been defined and initialized in your source program at task-build time. 


?The INIDM module is a dynamic memory management module (see Chapter 7) that is normally used with the 
virtual memory management routines. 


Four modules in the statistical version of the routines set up or maintain statistics of the use of 
the work file and memory. These modules and their associated statistical data fields are as follows: 


® The INIVS module, which initializes the following three double-word fields: 
— The total work file access field ($WRKAC) 
— The work file read count field ($WRKRD) 
—- The work file write count field (SWRKWR) 


Each of these fields is a double-word integer contained in the global data storage module 
(VMDAS) for the statistical version of the routines. 


® The CVRS module, which maintains the count of total work file accesses in the $WRKAC field. 


© The RDPAS module, which maintains a total of the work file reads in the $WRKRD field and a 
total of the work file writes in the $WRKWR field. 


® The GTCOS module, which maintains a count of the total amount of free dynamic memory in 
the $FRSIZ single-word field. This field must be defined and initialized in the source program. 


The statistical version of the virtual memory management routines does not automatically report 
these statistics. It is your responsibility to provide for the output of the statistical data in the fields 
described above if the statistical version of the routines is used. 


Yo use the statistical routines, specify at task-build time the virtual memory management routines 
library file, the names of all statistical modules whose routines will be used at task-execution 
time, and the name of the global data storage module. The only optional modules are ALSVB and 
INIDM. 
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The following specifications identify all modules of the statistical version of the routines: 


LB: [1,1] VMLIB/LB: ALBLK: ALSVB:ALVRT: CVRS :EXTSK:FNDPG:GTCOS 
LB: (1, 1] VMLIB/LB: INIVS:MRKPG: RDPAS: RQVCB: VMUTL: INIDM: VMDAS 


The nonstatistical routines use the global data storage module VMDAT. To use the aoneenteaiel 
routines, you specify at task-build time the virtual memory management routines library file, the 
names of all nonstatistical modules whose routines will be used at task-execution time, and the 
name of the global data storage module. The only optional modules are ALSVB and INIDM. | 


The following specifications identify all modules of the nonstatistical version of the routines: | 


LB: (1,1) VMLIB/LB: ALBLK: ALSVB: ALVRT: CVRL: EXTSK:FNDPG:GTCOR 
LB: (1, 1] VMLIB/LB: INIVM: MRKPG: ROPAG: RQVCB: VMUTL: INIDM: VMDAT 
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SINIVM—Virtual mernory initialization routine 


The $INIVM routine initializes the task’s free dynamic memory, sets up the page address control list, 
and initializes your disk work file to enable memory-to-disk page swapping. Disk work file capacity fs 
64K words. 


FORMAT 


CALL SINIVM 


INPUT 
$FRHD block 


In your source program: define and initialize a 2-word field named $FRHD. To define the fieid, 
include the following code in your source program: 


SFRHD:: .BLKW 2. 


To initialize the field, store the starting address of the free dynamic memory in $FRHD. 
globals 


In your source program: four global symbols as follows: 
WSKLUN Logical unit number (LUN) to be used for the work file. You must assign this LUN to a disk device. 


WS$KEXT Work file extension size (in blocks). A negative number indicates that the extend shouid first be 
requested as a contiguous allocation of disk biocks. A positive number indicates that the extend need 
not be contiguous. 


NSMPAG Fast page search page count. If there is sufficient dynamic memory to ailocate the number of pages 
specified, NSMPAG will set aside 512 words of dynamic memory to speed up the searching of 
memory-resident pages. 


SWRKPT Store the address of the FDB in the word $WRKPT before calling SINIVM. 


memory address 
In Register 1: the highest address of the task’s free dynamic memory 


OUTPUT 


Condition Code 


Initialization succeeded if both of the following conditions exist: 


© bit = Clear 
RegisterO = 0 


SINIVM 


Initialization failed if the following conditions exist: | 


C bit = Set 
RegisterO = One of the following values: 
—2 to indicate work file open failure 
-1 to indicate work file mark-for-deletion failure 


NOTE: Before calling the $INIVM routine, the task can call the $INIDM routine (sce 
Chapter 7), which returns the last address of dynamic memory and the total size of. 
dynamic memory. 


Also, you can examine the FCS error code at offset F.ERR in the work file FDB. The 
address of the FDB is stored in the word $WRKPT. 


DESCRIPTION 


Starting at the high address of the calling task’s free dynamic memory, the $INIVM routine clears 
control fields and the page address control listhead. The $INIVM routine then sets up the heading 
for a new page address control list and calls the Allocate Block Routine ($ALBLK) to allocate a 
memory page block for the control list. The $INIVM routine calls the $ALBLK routine to allocate 
a page block for the first memory page for the calling task, and links the first allocated page to the 
page control list. 


The $INIVM routine initializes (opens) your disk work file. If the file is opened successfully, | 
the $INIVM routine attempts to mark it for deletion. This ensures that the file will be deleted 


automatically when it is closed, or if the task terminates abnormally or exits. : 


NOTE: The work file can be closed by the operation CLOSE$ $WREPT. | 


The $INIVM routine destroys the contents of Registers 0 through 2. Whether or not the . 
initialization is successful, it transfers control to the $SAVRG routine, which restores Registers 
3 through 5 and returns to the calling task. 


The interaction of the $INIVM routine with your task and the Allocate Block Routine (SALBLIO is 
shown in Figure 81. 
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Figure 8-1 General Block Diagram of the SINIVM Routine 
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EXAMPLE | 


The following source statements call the $INIVM routine to initialize free dynamic memory and, 
then call $WRKPT to close the work file. In this example, the $INIDM routine provides the | 
required free memory address in Register 1: 


ESR4 =m 4 ; INSUFFICIENT WORK FILE OYNAMIC MEMORY 
ESR73 am 73 ; WORK FILE I/O ERROR 

ESR76 ald 76 ; WORK FILE EXCEEDED 

S$v2 = 302 ; SEVERITY 2 

WS KLUN = 4 + WORK FILE LUN 

NSMPAG =a 20 ; FAST PAGE SEARCH PAGE COONT 

WSKEXT = 24 WORK FILE EXTENSION SIZE (BLOCKS) 
SWRKPT: .WORD 0 ADDRESS OF FDB 


SFRHD:: .BLKW 2 
SFRSIZ: 1 
GENFLG: .WORD 0 
zl BIT 0 - VIRTUAL 


MOV #SFRHD, RO 
CALL SINIDM 
MOV R2, SFRSIZ 
CALL SINIVM 


FREE MEMORY LISTHEAD : a 
SIZE COUNT FOR FREE MEMORY 
GENERAL WORD FLAG 
ILE OPEN - 1 = OPEN, O = CLOSED 


SET ARG FOR FREE MEMORY HEAD 
INITIALIZE MEMORY 

SET ARG FOR SIZE 

INITIALIZE WORK FILE SUBSYSTEM 


. 


3 


te] ve Se Ye Ye Yo 


5 “Me Me 


=e 


CLOSES $WRKPT 
BIC #1, GENFLG 
RTS Pre 


CLOSE VIRTUAL WORK FILE 
CLEAR WORK FILE OPEN FLAG 


“es So 
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Virtual Memory Management Routines 


The core allocation routines manage the allocation and deallocation of space in the free dynamic 
memory of the executing task. The core allocation routines are as follows: 


The Allocate Block Routine (SALBLK), which provides the interface between the executing task 
and the other core allocation routines. That is, the executing task is provided all the services of 
the core allocation routines by simply calling the $ALBLK routine, or those routines that call 
the $ALBLK routine. 


The Get Core Routine ($GTCOR), which is always called by the SALBLK routine to perform the 
necessary processing to allocate the requested memory space from the free dynamic memory. 


The Request Core Block Routine ($RQCB), which is called by the $GTCOR routine to allocate 
the requested memory space if it is available in the free dynamic memory. 


The Write Page Routine ($WRPAG), which is called by the $GTCOR routine to transfer memory 
pages to your disk work file to free enough memory space to satisfy the memory allocation 
request. 


The Release Core Block Routine ($RLCB), which is called by the $GTCOR routine to release 
space previously allocated to a memory page that has been transferred to the disk work file. 


In addition to the five core allocation routines mentioned above, there is a sixth routine called the 
Extend Task Routine ($EXTSK), which is accessed by the statistical module GTCOS. The $EXTSK 
routine is called by the $GTCOR routine to extend the size of the task region, thus making enough 
memory available in the free dynamic memory to satisfy the allocation request. 


Do not confuse the statistical module GTCOS with the nonstatistical module GTCOR. Both of these 
modules are called by references to the entry point $GTCOR. $GTCOR calls $EXTSK only when 
you include the statistical module GTCOS at task-build time. If you do not include GTCOS, the 
$GTCOR routine uses the nonstatistical module GTCOR by default. 
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Fo _____— 
$ALBLK—Allocate block routine 


The $ALBLK routine determines whether a block of memory storage can be allocated from the free 
dynamic memory. If so, the $ALBLK routine clears (zeros) the allocated block and returns the resident 
memory address of the block to the calling task. If there is insufficient space in the free dynamic 
memory, the requested block cannot be allocated. | 

| 


FORMAT 


CALL $ALBLK 


INPUT 


block size 


| 
| 
In Register 1: the size (number of bytes less than or equal to 512,9) of the memory storage block 
to be allocated | 


error code 

In the task: the definitions for the following global symbols: 
E$R4 
S$V2 


OUTPUT : 


block address 
In Register 0: the dynamic memory address of the allocated, cleared block 


error response 
If allocation is unsuccessful, $ALBLK produces the following output: 


In Register 1: sets the error/severity codes E$R4 and S$V2 
In Register 2: saves the address of the argument block $F RHD (free memory header) 


The $ALBLK routine then calls the user $ERMSG routine. 


DESCRIPTION 


The $ALBLK routine calls the Get Core Routine ($GTCOR) to allocate the requested memory 
block, as follows: 


¢ Request allocation from the free dynamic memory 


¢ If the request is not met, attempt to extend the task region to increase the size of the free 
dynamic memory 


S$ALBLK 


¢ Ifthe task cannot be extended, swap unlocked pages from memory storage to disk to deallocate 
memory space for reallocation 


In addition to being called by the user task, the $ALBLK routine is called by the following virtual 


memory management routines: 


¢ Initialize Virtual Memory Routine ($INIVM), which calls $ALBLK to allocate initial blocks of 
dynamic memory to enable page swapping between disk and memory storage 


¢ Convert Virtual to Real Address Routine (§$CVRL), which calls $ALBLK to allocate a block of 
dynamic memory for a virtual page block 


¢ Allocate Virtual Memory Routine ($ALVRT), which calls $ALBLK to allocate a memory page 
block for a virtual page block that is to be swapped from memory to disk storage 


Figure 8—2 shows the interaction of the $ALBLK routine with a user task and other virtual 
memory management routines. 
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Figure 8-2 General Block Diagram of the $ALBLK Routine 
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request memory 
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routine 


EXAMPLE 


The following source statements call the $ALBLK routine to allocate a 4-byte block of memory and 
store the address of the block in buffer REFHD: 


ESR4 == 4 ? INSUFFICIENT WORK FILE DYNAMIC MEMORY , 
ESR73 ald 73 ; WORK FILE I/O ERROR | 
ESR76 = 76 + WORK FILE EXCEEDED | 
S$V2 = 2 ? SEVERITY 2 | 
REFHD: .BLKW 2 ; REFERENCE LISTHEAD | 
MOV R1, -(SP) 7 SAVE VIRTUAL ADDRESS OF REFERENCE 
MOV #4,R1 ; GET SIZE OF BLOCK 
CALL $$$S$ALBLK + ALLOCATE CORE BLOCK 
MOV RO, @REFHD+2 -; LINK REAL ADDRESS TO OLD LAST BLOCK ADDRESS 
MOV RO, REFHD+2 ; SET NEW LAST BLOCK ADDRESS | 
MOV (SP) +,2 (RO) 7 RECORD VIRTUAL ADDRESS OF REFERENCE 
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$GTCOR—Get core routine—nonstatistical module 
GTCOR 


The $GTCOR routine (defined in the nonstatistical module GTCOR) attempts to allocate requested 
dynamic memory blocks In the following ways: 


¢ Allocate memory from the currently available space in the free dynamic memory 


« Swap unlocked page blocks from dynamic memory to disk, freeing previously allocated memory 
space for reallocation 


FORMAT 


CALL $GTCOR 


INPUT 


block size 
In Register 1: the size (number of bytes less than or equal to 512;9) of the dynamic memory block 
to be allocated 


OUTPUT 


block address 
In Register 0: the memory address of the dynamic memory block, if allocated 


Condition Code 


C bit = Clear if the allocation was successful 
C bit = Set if the allocation failed 


5 SESE (ace (TR gee ae eNO SYNE TY Oe OO We I ED 


DESCRIPTION 


$GTCOR calls the Request Core Block Routine ($RQCB; described in Chapter 7) to determine 
whether enough free dynamic memory space is currently available to satisfy the allocation request. 
If so, the $GTCOR routine returns the memory address of the resident block to the caller. 


If the $RQCB routine cannot allocate the requested block from the current free dynamic memory, 
the $GTCOR routine searches for the unlocked pages currently resident in memory. If any 
unlocked pages are found, the least recently used (LRU) page is released and its memory space is 
allocated to the new page. If an unlocked page cannot be found, $GTCOR sets the C bit, indicating 
that it failed to find an unlocked page, and returns control to the caller. 
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When an LRU page is found, the $GTCOR routine checks the page to see if it has been written 
into. If so, the Write Page Routine (SWRPAG) is called to write the page to the disk work file., The 
Release Core Block Routine ($RLCB; described in Chapter 7) is called to release the page and the 
Request Core Block Routine ($RQCB) is called to allocate the page. The memory address of the 
allocated page returns in Register 0 to the caller. If the $GTCOR routine does not obtain sufficient 
memory for the requested block, it sets the C bit in the Condition Code and returns control to the 
caller. $GTCOR calls the $SAVRG routine to save and restore Registers 3 through 5 of the caller. 


The $GTCOR routine is always called by the Allocate Block Routine ($ALBLK). | 


| 
Figure 8-3 shows the interaction of the $GTCOR routine with other system library and virtual 
memory management routines. ! 


Figure 8-3 General Block Diagram of the $GTCOR Routine (Nonstatistical Module GTCOR) 
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EXAMPLE 


The following source statements call the $GTCOR routine to allocate a memory block of one byte 


plus the length of the header: 


ESR4 =m 
ESR73 == 
ESR76 =m 
S$V2 = 
LENGTH: .BLKW 
ADSZ: - BLKW 
- EVEN 
MOV 
MOV 
ADD 
ADD 
CALL 
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#1, RO 

RO, LENGTH 
#HDSZ,R1 
RO,R1 
SGTCOR 
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WORK FILE I/O ERROR 

WORK FILE EXCEEDED 

SEVERITY 2 

LENGTH OF RECORD JUST READ 

LENGTH OF HEADER 


SET LENGTH TO ONE BYTE 

REMEMBER THE LENGTH 

ADD HEADER LENGTH 

ADD ALLOWANCE FOR MODIFICATIONS 
ALLOCATE SPACE 


$GTCOR 


$GTCOR—Get core routine—statistical module 
GTCOS 


The $GTCOR routine (accessed by the statistical module GTCOS) attempts to allocate requested 
dynamic memory blocks in one of the following ways: 


| 
* Allocate memory from the currently available space in the free dynamic memory | 


e Extend the task region, increasing the size of the free dynamic memory to accommodate he 
allocation request 


Swap unlocked page blocks from dynamic memory to disk, which frees previously allocated memory 
space for reallocation | 


FORMAT . | 


CALL $GTCOR | 


INPUT 


block size 
In Register 1: the size (number of bytes less than or equal to 51219) of the dynamic block memory 
to be allocated 


OUTPUT 


address 
In Register 0: the memory address of the dynamic block, if allocated 


Condition Code 


C bit = Clear if the allocation was successful 
C bit = Set if the allocation failed 


DESCRIPTION 


The Request Core Block Routine ($RQCB; described in Chapter 7) is called to determine whether 
enough free dynamic memory space is currently available to satisfy the allocation request. If|so, 
the $GTCOR routine returns the memory address of the resident block to the caller. 


If the requested block cannot be allocated from the current free dynamic memory, the $GTCOR 
routine calls the Extend Task Routine ($EXTSK) to determine whether the task region can be 
extended to make available the requested space in the free dynamic memory. If so, the #GTCOR 
routine returns the memory address to the caller. 
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If the task region cannot be extended, the $GTCOR routine searches for unlocked pages currently _ 
resident in memory. If any unlocked pages are found, the least recently used (LRU) page is 
released and its memory space is allocated to the new page. 


When an LRU page is found, the $GTCOR routine checks the page to see if it has been written 
into. If so, the Write Page Routine (?WRPAG) is called to write the page to the disk work file. The 
Release Core Block Routine ($RLCB; described in Chapter 7) is called to release the page and the 
Request Core Block Routine ($RQCB) is called to allocate the page. The memory address of the 
allocated page is returned in Register 0 to the caller. If the $GTCOR routine is not able to obtain 
sufficient memory for the requested block, it sets the C bit in the Condition Code and returns 
control to the caller. The $GTCOR routine calls the $SAVRG routine to save and subsequently 
restore Registers 3 through 5 of the caller. 


The $GTCOR routine is always called by the Allocate Block Routine ($ALBLK). 


Figure 8-4 shows the interaction of the $GTCOR routine with other system library and virtual 
memory management routines. 
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Figure 8-4 General Block Diagram of the $GTCOR Routine (Statistical Module GTCOS) 
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$EXTSK—Extend task routine 


The $EXTSK routine extends the current region of the task to increase the amount of available memory 
for allocation. It extends the task region by the specified size rounded to the next 32-word boundary. 


FORMAT 
CALL SEXTSK 
INPUT 

block size 


In Register 1: the size (number of bytes less than or equal to 51219) of the memory storage block 
to be allocated 


OUTPUT 


extension size 


In Register 1: the actual extension size (requested size rounded to next 32-word boundary) 


Condition Code 


C bit wz Clear if extension was successful 
C bit = Set if extension failed 


DESCRIPTION 


The $EXTSK routine is called by the Get Core Routine ($GTCOR) when there is insufficient space 
in the current free dynamic memory to satisfy a memory block allocation request. The $EXTSK 
routine rounds the requested extension size to the next 32-word boundary. If there is enough 
memory space available, $£XTSK extends the task region, returning the total amount of the 
extension, in Register 1, to the $GTCOR routine. It preserves all other registers of the caller. If 
it cannot extend the task region, the $EXTSK routine sets the C bit in the Condition Code and 
returns to the $GTCOR routine. 


While you can call the $EX‘TSK routine directly, the routine is also called by the Initialize Dynamic 
Memory Routine ($INIDM), described in Chapter 7. 


Figure 8—5 shows the interaction of the $£XTSK routine with the $GTCOR routine (in statistical 
module GTCOS). 
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Figure 8-5 General Block Diagram of the $EXTSK Routine 
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EXAMPLE 


The following source statements call the $EXTSK routine to extend the amount of memory 
available to the task: 
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TSKINC == 
TSKMAX =m 
PSTADDR: .WORD 
FRHD: - BLKW 


CALL 
LOS: 


256. 
0 
e) 
2 


$SAVRG 


R1,-(SP) 
#FRHD, RO 
SRQCB 

608 
#PSTADDR, R3 
(R3),R2 
R2, #TSKMAX 
1738 
#TSKINC,R1 
SEXTSK 
ERRS 

R1, FRHD 
R1, (R3) 
478 , 


#-1, (R3) 


#FRHD, RO 
$RLCB 
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$WRPAG—Write page routine | 


The $WRPAG routine transfers a memory page to the disk work file. 


FORMAT | 


CALL $WRPAG | 


INPUT 


page address 
In Register 2: the dynamic memory address of the page to be transferred to disk 


error code 
In the task: the definitions for the following global symbols: 


E$R73 
S$V2 


OUTPUT 


Condition Code 


C bit = Clear if transfer succeeded 
C bit = Set if transfer failed — 


error response 
If transfer is not successful, $WRPAG produces the following output: 


In Register 1: sets the error/severity codes E$R73 and S$V2 
The $WRPAG routine then calls the user $ERMSG routine. 


DESCRIPTION | 


The $WRPAG routine is called by the Get Core Routine ($GTCOR) to transfer to your disk work 
file a resident memory page that has been written into. 


The $WRPAG routine calls the $SAVVR routine to save and subsequently restore Registers 0 
through 2 of the caller. The routine then performs the following actions: 


¢ Sets up the disk work file address of the page to be transferred | 


¢ Initiates the page-writing operation 


¢ (Checks the status of the write operation 


SWRPAG 


e Indicates a successful transfer (clears the C bit in the Condition Code) and returns control to 
the $SAVVR routine, or calls your $£RMSG routine if a fatal work file I/O error prevented the 


page transfer 


Figure 8-6 shows the interaction of the $WRPAG routine with the $GTCOR routine. 
Figure 8-6 General Block Diagram of the $WRPAG Routine 
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EXAMPLE 


The following source statements call the $WRPAG routine to transfer a memory page from buffer 


P$GNXT to the disk work file: 


ESR4 = 4 

ESR73 =m Bs 

ESR76 == 76 

S$Vv2 = 302 

PSGNXT: .WORD 0 

MOV R4,R5 

MOV PSGNXT, R4 
MOV R4,R2 


CALL SWRPAG 


INSUFFICIENT WORK FILE DYNAMIC MEMORY 
WORK FILE I/O ERROR 
WORK FILE EXCEEDED 
SEVERITY 2 

NEXT PAGE WORK FILE 


SAVE PREDECESSOR 
GET NEXT PAGE 


SET UP BUFFER FOR TRANSFER 
WRITE OUT PAGE INTO DISK WORK FILE 
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Virtual Memory Allocation Routines 


Virtual memory allocation routines manage the allocation of disk and memory storage to enable 


page swapping from the free dynamic memory to your disk work file. The three virtual memory 
allocation routines are as follows: 


¢ Allocate Virtual Memory Routine ($ALVRT), which allocates disk and memory page blocks, 
maintains page control and address tables, and interfaces with the executing task and the cor 
allocation and page management routines. 


¢ Allocate Small Virtual Block Routine ($ALSVB), which allocates small page blocks of disk 
and memory storage within large page blocks to enable efficient use of storage. The $ALSVB 
routine interfaces with the $ALVRT routine and page management routines to ensure address 
and status control of small pages in memory and disk storage. 


¢ Request Virtual Core Block Routine ($RQVCB), which manages page-block allocation on your 
disk work file when it is called by the $ALVRT routine. 
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$ALVRT 


$ALVRT—Allocate virtual memory routine 


The $ALVRT routine determines whether a page block of virtual storage can be allocated on your, 
disk work file. If so, the $ALVAT routine allocates an equal amount of memory storage, updates page 
control and address tables, and returns the disk and memory addresses of the allocated page blocks 
to the caller. If the SALVRT routine cannot allocate the requested storage, the error and severity codes 
E$R76 and S$V2 are stored in Register 1 and the user's $ERMSG routine is called. _ | 


FORMAT 


CALL $ALVRT 


INPUT 


block size 
In Register 1: the number of bytes to be allocated 


NOTE: The maximum size of a page block is 512;9 bytes. | 


OUTPUT 


memory address 


In Register 0: the memory address of the allocated page block 
In Register 1: the virtual address of the allocated page block 


DESCRIPTION ! 


The $ALVRT routine calls the Request Virtual Core Block Routine ($RQVCB) to determine whether 
the requested storage can be allocated on the disk work file. If not, a fatal error is signalled and 
the $ALVRT routine calls your $ERMSG routine. If it can allocate the disk storage, the $RQVCB 

routine returns the disk page block address to the $ALVRT routine, which determines whether a 

page block of space is available in memory. If not, the Allocate Block Routine (SALBLK) is called to 
allocate a page block. The $ALVRT routine then calls the Convert Virtual to Real Address Routine 
($CVRL) to convert the virtual address to a memory address. 


The $ALVRT routine calls the Write-Marked Page Routine ($WRMPG) to set the “written into” 
flag of the memory page. It also calls the $SAVRG routine to save and restore Registers 3 

through 5 of the calling routine. Although you can call the $ALVRT routine directly, it is also’ 
called automatically by the Allocate Small Virtual Block Routine ($ALSVB). Figure 8-7 shows) 
the interaction of the $ALVRT routine with your task and other virtual memory management 
routines. 
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SALVRT 


Figure 87 General Block Diagram of the $ALVRT Routine 
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Call user's 
SERMSG 
ROUTINE 


Call SALBLK to 
allocate core 
page block 


Updates 


pe 
tables 


SERMSG 


SALVRT 


EXAMPLE | 


The following source statements call the $ALVRT routine to allocate a page block of virtual memory 
on a disk file. In this example, the statements save the contents of Registers 0 and 2 before calling 
$ALVRT: 


ESR4 == 4 + INSUFFICIENT WORK FILE DYNAMIC MEMORY 
ESR73 =m 73 ; WORK FILE I/O ERROR 
ESR76 =m 76 ; WORK FILE EXCEEDED 
S$v2 == 302 ; SEVERITY 2 
TEMP1i: .WORD 0 ; TEMPORARY BUFFER FOR VIRTUAL MEMORY | 
TEMP2: .WORD 0 ; TEMPORARY BUFFER FOR VIRTUAL MEMORY 
A.LEN: .BLKW i ; LENGTH OF VIRTUAL ELEMENT | 
MOV RO, TEMP 1 + SAVE POINTER IN INPUT BUFFER 
MOV R2, TEMP2 ; SAVE NUMBER OF BYTES IN BUFFER 
MOV A.LEN,R1 + LENGTH OF VIRTUAL ELEMENT TO REGISTER 1 


CALL SALVRT ALLOCATE VIRTUAL BLOCK 
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SALSVB 


$ALSVB—Allocate small virtual block routine 


The $ALSVB routine allocates small page blocks within large page blocks of disk and memory storage. 
Thus, the routine accommodates varialsie user allocation size requirements and minimizes wasted 
storage space. 


The $ALSVB routine initially allocates a large page block, then performs suballocation of requested — 
smail blocks within the large block. When the space within a large block is exhausted, a new large 
block is allocated by the $ALSVB routine. 


FORMAT 


CALL SALSVB 


INPUT 


memory block 


In the source program: a large memory block defined as follows: 


NSDLGH == 512. 


NOTE: Normally, 512 is the size of a large memory block. In any case, it must be less 
than or equal to 5129. 


page block size 
In Register 1: the size of the page block to be allocated, where: 


R1 = Zero (0) to force the allocation of a large virtual page block on the first call to $SALSVB 
R1 = A value less than or equal to 512;9 specifying the size, in bytes, of the smail page to be allocated 


OUTPUT 


In Register 0: the dynamic memory address of the allocated page block 


virtual address 
In Register 1: the virtual address of the allocated block 


DESCRIPTION 


When a small page block is to be allocated within an existing large page block, the $ALSVB routine 
calls the Convert Virtual to Real Address Routine ($CVRL) to do the following: 


° Locate the allocated large page, if it is memory-resident (if it is not resident, read the page 
from disk to memory) 


© Convert the virtual page address to a memory page address 


8-30 


$ALSVB 


| 
¢ Transfer the large page block from disk into the large memory page block | 


The S$ALSVB routine calls the Write-Marked Page Routine ($}WRMPG) to set the “written into” flag 
of the allocated memory page. 


When a large page block is to be allocated, the Allocate Virtual Memory Routine ($ALVRT) is called 
to do the following: | 


¢ Allocate the disk and dynamic memory of the requested large page block 
¢ Convert the virtual address to a memory address 


¢ Transfer the large block, if necessary, from disk to dynamic memory 


¢ Set the “written into” flag of the allocated page block | 


The $ALSVB routine destroys the contents of Register 2 and preserves the contents of Registers 3 
through 5. 


Figure 8—8 shows the interaction of the $ALSVB routine with other virtual memory management 
routines. 


Ls 


- $ALSVB 


Figure 8-8 General Block Diagrarn of the $SALSVB Routine 
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EXAMPLE 


The following source statements call the $ALSVB routine to allocate a block of memory within a 
larger block: | 


INSUFFICIENT WORK FILE DYNAMIC MEMORY | 


ESR4 =a 4 ; 
ESR73 sue 73 ; WORK FILE I/O ERROR | 
ESR76 =u 76 ; WORK FILE EXCEEDED 
$sv2 == 302 3; SEVERITY 2 
NSDLGH == 512. ; LARGE BLOCK SIZE 
PSGSIZ == 24 : SIZE OF CURRENT PAGE | 
MOV #PSGSIZ,RS5 ; GET PAGE SIZE 
MOV R5,-R1 ; COPY SIZE OF TABLE 
ASL Rl ; CONVERT TO BYTES 
CALL SALSVB ; ALLOCATE VIRTUAL MEMORY 
MOV Rl, (R4) + ; SAVE VIRTUAL ADDRESS 
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$RQVCB—Request virtual core block routine 


The $RQVCB routine manages page-block allocation on your disk work file. The $ROVCB routine is 
called by the Allocate Virtual Memory Routine (SALVRT) when your task has requested allocation of a 
page block of a maximum of 51219 bytes in length. 


The $RQVCB routine is not a user-called routine. 


DESCRIPTION 


The $RQVCB routine rounds the requested number of bytes up to the nearest word. If the rounded 
value crosses a disk block boundary, the $RQVCB routine allocates the page block beginning at the 
next disk block. 


If allocation is successful, the 3RQVCB routine clears the C bit in the Condition Code and returns 
the disk address of the allocated page to the $ALVRT routine. 


If allocation is not successful, the $RQVCB routine sets the C bit in the Condition Code and 
returns control to the $ALVRT routine. The following conditions can prevent allocation: 


e¢ There is no more disk storage space available. 


e A page block size greater than 51219 bytes has been requested. 
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$RQVCB 


Figure 8-9 General Block Diagram of the $RQVCB Routine 
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Virtual Memory Management Floutines 


The page management routines perform the processing required to control page swapping between 
dynamic memory and disk file storage. This processing includes address conversion; page location; 
page transfer from disk to memory; and page status handling such as timestamping, flagging as 
“written into,” and locking and unlocking memory pages. 


The page management routines are as follows: 


The Convert and Lock Page Routine ($CVLOK), which converts a virtual address to a dynamic 
memory address and locks the page in memory when called by your task 


The Convert Virtual to Real Address Routine ($CVRL), which converts a virtual address to a 
dynamic memory address when called by one of the following: 


— User task 
~ Allocate Virtual Memory Routine ($ALVRT) when a new disk page has been allocated 


—- Convert and Lock Page Routine ($CVLOK) when a page address is to be converted and the 
page is to be locked in memory 


Read Page Routine ($RDPAG), which is called by the sore routine to transfer a page from 
your disk work file to dynamic memory 


Find Page Routine ($FNDPG), which determines whether a virtual page is resident in dynamic 
memory when called by one of the following: 


- §$CVRL routine 

~ Lock Page Routine ($LCKPG) 

- Unlock Page Routine (SUNLPG) 

- Write-Marked Page Routine ($WRMPG) 


Write-Marked Page Routine (S5WRMPG), which sets the “written into” flag of memory pages 
when called by a user or by the $ALVRT and $ALSVB virtual memory allocation routines 


Lock Page Routine ($LCKPG), which is called by the $CVLOK routine and a user task to set a 
lock byte in a memory page to prevent its being swapped from memory to the disk file 


Unlock Page Routine (SUNLPG), which is called by a user task to clear a lock byte in a memory 
page to allow it to be swapped to disk storage to free memory space for reallocation 
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$CVLOK—Convert and lock page routine : 


The $CVLOK routine performs the following functions: 
¢ Converts a virtual address to a memory address 
° Locks the page in memory 


FORMAT 


CALL $CVLOK 


INPUT 


virtual address 


In Register 1: the virtual address you want to convert 


OUTPUT 


converted memory address 
In Register 0 


virtual address 
In Register 1 


Condition Code 


C bit = Clear if the address was converted and the page locked 


C bit = Set if address conversion or page locking failed 


DESCRIPTION 


The $CVLOK routine calls the following routines: 


© The Convert Virtual to Real Address Routine ($}CVRL) to convert the virtual address to a 
memory address 


* $CVRL to preserve the contents of Registers 3 through 5 
¢ The Lock Page Routine ($LCKPG) to lock the page in memory 


$CVLOK also preserves the contents of Register 2. 


$CVLOK 


Figure 8-10 General Block Diagram of the $CVLOK Routine 
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EXAMPLE 


$CVLOK 


The following source statements call the $CVLOK routine to convert a virtual address from the 
listhead to a dynamic memory address in TEMP! and then an error routine in case the conversion 


fails: 


ESR4 
ESR73 
ESR76 

' S$V2 
TEMP 1: 
LISTHD: 


LCKERR: 


LISTHD, Rl 
SCVLOK 
LCKERR 
RO, TEMP 1 


#ERRS5S, RO 
ERROR 


. 
Se Ne Ne te Me Ne 


Se Se 3e fe 


CONVERT, 
ERROR 
SAVE IN TEMPORARY BUFFER 


GET ERROR MESSAGE 
GET ERROR ROUTINE 


INSUFFICIENT WORK FILE DYNAMIC MEMORY | 
WORK FILE I/O ERROR 
WORK FILE EXCEEDED 


SEVERITY 2 


‘TEMPORARY STORAGE FOR VIRTUAL MEMORY | 
LISTHEAD LOCATION 


MOVE VIRTUAL ADDRESS 
STORE REAL ADDRESS IN REGISTER 0 


| 
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$CVRL—Convert virtual to real address routine 


The $CVAL routine converts a virtual acidress to a dynamic memory address. Virtual address units are 
words and dynamic memory addresses are bytes. 


FORMAT 


CALL $CVRL 


INPUT 


virtual address 


In Register 1: the virtual address you want to convert 


OUTPUT 


memory address 
In Register 0: the converted memory address 


DESCRIPTION 


The $CVRL routine can be called directly in the task or indirectly by the following routines: 
¢« Allocate Virtual Memory Routine ($ALVRT) when a new disk page has been allocated 


¢ Convert and Lock Page Routine ($CVLOK) when the executing task has specified that a virtual 
address is to be converted to a memory address and the page is to be locked in memory 


The $CVRL routine calls the Find Page Routine ($FNDPG) to determine whether the specified 
page is resident in memory. If so, the virtual address is converted to a memory address, which 

is returned to the caller. If the page is not in memory, $CVRL calls the Allocate Block Routine 
($ALBLE) to allocate a memory page block. The $CVRL routine then calls the Read Page Routine 
($RDPAG) to transfer the disk page into dynamic memory. The page address is then converted to a 
memory address. The memory address of the specified word in the page is stored in Register 0, and 
control is transferred to the $SAVRG routine, which restores Registers 3 through 5 and returns to 
the caller. 


The $CVRL routine leaves Register 1 unchanged. It destroys the contents of Register 2. 


$CVRL 


Figure 8-11 General Block Diagram of the $CVRL Routine | 
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$CVRL 


EXAMPLE 


The following source statements call the $CVRL routine to convert a virtual address in Register 1 
to a dynamic memory address and store the result in Register 0: 


ESR4 == 
ESR73 = 
ESR76 = 
s$v2 as 
PSGSIZ = 
PSGADR: .BLKW 


MOV 
MOV 
TST 
BNE 
MOV 
CALL 
MOV 


208: CALL 


4 
73 
76 
302 
24 
1 


#PSGADR,R1 
R1,R5 

Rl 

205 
#PSGSTZ,R1 
SALBLK 
RS,R1 
SCVRL 


ee Ve Ze Ye Ye Vo 


we Se Ve We Re We Va Ne 


INSUFFICIENT WORK FILE DYNAMIC MEMORY 
WORK FILE I/O ERROR 

WORK FILE EXCEEDED 

SEVERITY 2 : 
SIZE OF CURRENT PAGE 

ADDRESS OF CURRENT PAGE 


GET PAGE ADDRESS 

SAVE VIRTUAL ADDRESS 

IS REQUEST ON BLOCK BOUNDARY? 
IF NO, BLOCK ALREADY EXISTS 
CREATE A PAGE BUFFER 
ALLOCATE STORAGE SPACE 
RESTORE VIRTOAL ADDRESS 
CONVERT TO REAL ADDRESS 


$RDPAG—Read page routine 


The $RDPAG routine transfers a disk page from the work file to the dynamic memory. 


FORMAT 


CALL $RDPAG 


INPUT 


page address 


In Register 0: the disk address of the page you want to transfer 


OUTPUT 


Condition Code | 


Chit = Clear if transfer succeeds | 
C bit = Set if transfer fails | 


DESCRIPTION 


The $RDPAG routine is called by the Convert Virtual to Real Address Routine ($CVRL) when a 
disk page is to be transferred to ‘dynamic memory. The $RDPAG routine then does the following 


Sets up the address of the page to be transferred 


e¢ Initiates the page-reading operation 


Checks the status of the read operation 
* Calls the $SAVVR routine to save and subsequently restore the caller's Registers 0 through 2 


The interaction of the $RDPAG routine with the task and the $CVRL routine is shown in 
Figure 812. 


$RDPAG 


Figure 8-12 General Block Diagram of the $SRDPAG Routine 


Initiate read 
operation 


Check status 
of read 


Set C bit: 
cail user's 
SERMSG 


_ routine 


Clear C bit; 
transfer to 
SSAVVR to 
restore RO = RZ 
and return 


-$RDPAG 


EXAMPLE 


The following source statements allocate a page in buffer P$GSIZ and call the $RDPAG routine to 


read the virtual page address into core memory: 


ESR4 
ESR73 
ESR76 
S$V2 
PSGSIZ 
PSGBLK: 
LISTHD: 
PAGLS: 


SCVRT: 


- BLKW 
- BLKW 
- BLKW 


SAVRG 
MOV 
SWAB 
CALL 
Bcc 
MOV 
CALL 
MOV 
BEQ 
CLR 
BISB 
ASL 
ADD 
MOV 


MOVB 
CALL 


R1,R5 

R5 
SENDPG 
10S 
#PSGSIZ,R1 
SALBLK 
PAGLS, R4 
5$ 

R2 

RS,R2 

R2 

R2, R4 
RO, (R4) 


R5, P$GBLK (RO) 


SRDPAG 
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- $FNDPG 


SFNDPG—Find page routine 


The $FNDPG routine searches an internal page address list to determine whether a virtual page has 
already been transferred into an allocated memory page block. 


FORMAT 

CALL $FNDPG 
INPUT 

virtual page address 


In Register 1: the address of the page being searched for 


OUTPUT 


block address 
In Register 0: the memory page block address where the page is resident 


Condition Code 


C bit «= Clear if page is resident 
C bit =| Set if page was not found 


DESCRIPTION 


The $FNDPG routine is called by the following virtual memory management routines: 


© Convert Virtual to Real Address Routine ($CVRL) when a virtual address is to be converted to 
a memory address 


¢ Lock Page Routine ($l.CKPG) when a memory page is to be locked in core memory 
* Unlock Page Routine ($}UNLPG) when a locked memory page is to be unlocked 


¢ Write-Marked Page Routine ($WRMPG) when the “written into” flag is to be set in a memory 
page 


The $FNDPG routine determines whether the specified page is resident in the task’s dynamic 
memory. If so, the page is timestamped, its page block address is set in Register 0, the C bit in 
the Condition Code is cleared, and control returns to the caller. If the page is not resident in 
memory, the $FNDPG routine sets the C bit in the Condition Code and returns control to the 
caller. $F NDPG does not change the contents of Register 1. 


$FNDPG 


The interaction of the $FNDPG routine with a user task and the page management routines is 
shown in Figure 8-13. 


Figure 813 Generai Block Diagram of the SFNDPG Routine 
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EXAMPLE | 


The following source statements call the $FNDPG routine to verify that a page address, stored in 
buffer P$GADR, exists in core memory. The example then calls $ALBLK to allocate the page block: 


PSGADR: .WORD 0 ; VIRTUAL PAGE ADDRESS | 
PS$GSIZ == 24 ? SIZE OF PAGE | 
CALL S$ SAVRG + SAVE NONVOLATILE REGISTERS | 
MOV _ PSGADR, R1 ; GET PAGE ADDRESS 
CALL SFNDPG 7 SEARCH FOR PAGE 
Bcc 10$ ; IF CLEAR, PAGE IN CORE. 
MOV #PSGSIZ,R1 : GET SIZE OF PAGE BUFFER 


CALL SALBLK ALLOCATE MEMORY 
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$WRMPG—Write-marked page routine 


The $WRMPG routine sets the “written into” flag of the specified page in dynamic memory. 


FORMAT 

CALL SWRMPG 
INPUT 

virtual page address 


In Register 1: the address of the page for which the flag is being set 


OUTPUT 


Condition Code 


C bit = Clear if the page was write-marked successfully 
C bit = Set if the specified memory page was not resident in the task’s free dynamic memory 


DESCRIPTION 


The $WRMPG routine is called by the following virtual memory management routines: 


° Allocate Virtual Memory Routine ($ALVRT) when a disk page has been allocated in dynamic 
memory 


* Allocate Small Virtual Block Routine ($ALSVB) when a small page block has been allocated 
within a large page block 


$WRMPG calls the Find Page Routine ($FNDPG) to dewenine whether the specified page is 
resident in the task’s memory. If not, the C bit in the Condition Code is set and control is 
transferred to the $SAVVR routine to restore Registers 0 through 2 and return to the caller. If 
the page is resident in memory, its “written into” flag is set, the C bit in the Condition Code is 
cleared, and control is transferred to the $SAVVR routine to restore Registers 0 through 2 and 
return to the caller. 


The interaction of the SWRMPG routine with the caller and virtual memory management routines 
is shown in Figure 8—14. 


$WRMPG 


Figure 8-14 General Block Diagram of the {WRMPG Routine | 
Call SFNDPG 
to find page 

| 
Set C bit: return 
to SSAVVR 
| 
Set write-mark | 
flag: clear C bit: 
return to 
SSAVVR _ 
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S$WRMPG 


EXAMPLE 


The following source statements call the $WRMPG routine to mark a page and then call an error 
routine in case $WRMPG is not successful: 
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TEMP 1: 
FREECT: 
ERS@: 


WRMERR ; 


» WORD ) + TEMPORARY STORAGE FOR VIRTUAL MEMORY 

-BLKW 1 ; NUMBER OF AVAILABLE PAGE ENTRIES 

-ASCIZ <15>/ACNT--Work file - page mark / 

- EVEN 

MOV TEMP1,R1 ; SET SWRMPG ARGUMENT 

MOV R5, TEMP1 ; MOVE PREV PAGE ADDRESS TO VIRTUAL MEMORY 
MOV @RO, @R3 ; UPDATE PREV VIRTUAL ADDRESS PAGE POINTER 
INC FREECT ; INCREMENT NUMBER OF PAGES AVAILABLE 

CALL SWRMPG *; MARK PAGE “WRITTEN INTO" 

BCS WRMERR 7 ERROR 

MOV #ER58, RO 7 GET ERROR MESSAGE 

BR ERROR ; GET ERROR ROUTINE 


$LCKPG 


$LCKPG—Lock page routine 


The $LCKPG routine sets a lock byte in a memory-resident page to prevent its being swapped ft trom 


dynamic memory to the disk work file. 


FORMAT 


CALL $LCKPG 


INPUT 


virtual page address 


In Register 1: a virtual address in the page to be locked in dynamic memory 


OUTPUT 


Condition Code 


C bit = Clear if the page was locked in memory 
Chit = Setif the page was not found 


DESCRIPTION 


The $LCKPG routine can be called by a user task or by the Convert and Lock Page Routine 
($CVLOK). 


$LCKPG calls the Find Page Routine ( $FNDPG) to determine whether the memory page is 


resident. If so, the page lock byte is set, the C bit in the Condition Code is cleared, and control is 


transferred to the $SAVVR routine to restore Registers 0 through 2 and return to the caller. 


If the specified page is not in memory, the $LCKPG routine sets the C bit in the Condition Code 


and returns control, by means of the $SAVVR routine, to the caller. 


The interaction of the $LCKPG routine with the task and page management routines is shown in 


Figure 8-15. 
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$LCKPG 


Figure 8-15 General Block Diagram of the $LCKPG Routine 
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$LCKPG 


EXAMPLE 


The following source statements call the $LCKPG routine to lock a page in dynamic memory if the 
listhead contains more than one element: 


TEMP1: .WORD 0 ; TEMPORARY STORAGE FOR VIRTUAL MEMORY | 
LISTHD: .BLKW 1 : LISTHEAD LOCATION 3 
ERSS: -ASCIZ <15>/ACNT --Work file - page lock / | 
-EVEN ! 
MOV LISTHD, R1 ; MOVE 1ST VIRTUAL ADDRESS 
CALL $CVLOK ; 1ST PAGE REAL ADDRESS IN REGISTER 0 
BCS LCKERR : ERROR | 
TST (RO) ; ONLY 1 ELEMENT? 
BNE 40$ ; NO, MORE THAN ONE | 
CALL SUNLPG ; YES, ONLY ONE, UNLOCK IT 7 
-40$: MOV TEMP1,R1 SET UP VIRTUAL ADDRESS FOR S$LCKPG 


CALL SCVRL SAVE REAL ADDRESS OF NEXT PAGE IN REGISTER 


 -o Yo Ne Fe 


CALL SLCKPG LOCK | 
BCS LCKERR ERROR : 
LCKERR: MOV #ERRS5, RO ; GET ERROR MESSAGE | 
BR ERROR ; ERROR ROUTINE | 
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SUNLPG—Unlock page routine 


The $UNLPG routine clears a lock byte in a memory-resident page to allow the page to be swapped 
from dynamic memory to the disk work file. 


FORMAT | 
CALL SUNLPG 

INPUT 

virtual page address 


In Register 1: the virtual address of the page you want to unlock 


OUTPUT 


Condition Code 


C bit = Clear if the page was unlocked 
Chit = Set if the page was not found 


DESCRIPTION 


$UNLPG calls the Find Page Routine ($FNDPG) to determine whether the memory page is 
resident. If so, the page lock byte and the C bit in the Condition Code are cleared and control is 
transferred to the $SAVVR routine to restore Registers 0 through 2 and return to the caller. 


If the specified page is not in memory, the C bit in the Condition Code is set and control is 
returned, by means of the $SAVVR routine, to the caller. 


The interaction of the $UNLPG routine with the task is shown in Figure 8-16. 
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SUNLPG 


Figure 8-16 General Block Diagram of the $UNLPG Routine 
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SUNLPG 


EXAMPLE 


The following source statements call the $UNLPG routine to allow pages to be swapped from real 


memory to virtual memory: 


TEMP1: .WORD 
TEMP2: .WORD 
FREECT: .BLKW 
LISTHD: .BLKW 
ERS6: -ASCTZ 
. EVEN 


10S: MOV 
MOV 
MOV 
CLR 
CALL 
BCS 


208: P 
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0 ; TEMPORARY STORAGE FOR VIRTUAL MEMORY 

0 7; TEMPORARY STORAGE FOR VIRTUAL MEMORY 

1 ; NUMBER OF AVAILABLE PAGE ENTRIES 

1 ; LISTHEAD LOCATION 

<15>/ACNT --Work file - page unlock / 

#LISTHD, TEMP2 ; GET FIRST REAL ADDRESS POINTER 
LISTHD, R1 7; MOVE FIRST VIRTUAL ADDRESS 

R1, TEMP 1 ; SAVE IN SECOND VIRTUAL ADDRESS BUFFER 
FREECT 7; CLEAR NUMBER OF SWAPS PER PASS 
CVLOK 3 PUT REAL ADDRESS IN REGISTER 0 
LCKERR + ERROR, PAGE LOCK FAILED 

(RO) 7; LINK = 0, ONLY ONE ELEMENT? 
205 7; NO, MORE THAN ONE 

SUNLPG 7; YES, ONLY ONE, UNLOCK IT 
UNLERR ; ERROR 


Summary Procedures 


The procedures for using the system library routines are summarized in the tables in this chapter. 
These summaries are presented as quick reference guides for users who are familiar with the 
detailed procedures and requirements for using individual routines, as described in the preceding 
chapters of this manual. : 


Table 9~1 Register Handling Routines Summary 


Routine Name/ 


Mnemonic Function Call Statement 
Save All Registers Saves/restores RO—RS5 CALL $SAVAL 
$SAVAL 

Save Registers 3—5 Saves/restores R3—AS JSR RS,SSAVRG 
S$SAVRG 

Save Registers 0O—2 Saves/restores RO—R2 JSR R2,$SAVVR 
$SAVVR 

Save Registers 1—5 Saves/restores R1i—RS5 JSR R5,.SAVR1 
SAVR1 


Table 9-2 Arithmetic Routines Summary 


Routine Name/ input Arguments and 
Mnemonic Call Statement Output | 
Integer Multiply RO = Multiplier RO = Product (high-order part) 
$MUL R1 = Multiplicand Ri = Product (low-order part) 
CALL $MUL R2—RS5 preserved 
Integer Divide RO = Dividend RO = Quotient 
$DIV R1 = Divisor Ri = Remainder 
CALL $DIV R2—R5 preserved 
Double-Precision Multiply RO = Multiplier RO = Product (high-order part) 
SOMUL Multiplicand: Ri = Product (low-order part) 
R2 = High-order part R4—R5 preserved 
R3 = Low-order part R2—R3 destroyed 
CALL $0MUL C = Clear 
Double-Precision Divide RO = Unsigned divisor RO = Remainder 
$DDIV Dividend: R1 = Quotient (high-order part) 
Ri «= High-order part R2 = quotient (low-order part) 
R2 = Low-order part R3 preserved 
CALL $DDIV 


Summary Procedures 


Table 9-3 Input Data Conversion Routines Summary 


Routine Name/ 


Input Arguments and 


Mnemonic Call Statement Output 
Decimal to R3 = Output address Successful: 
Binary Double R4 = Number input characters Converted number at output 
Word RS = Input siring address address: 
.DD2CT CALL .DD2CT Word 1 = High-order part 
Word 2 = Low order part 
C = Clear 
Unsuccessful: 
C = Set 
. All registers preserved 
Octal to R3 = Output address Successful: 
Binary Double R4 = Number input characters Converted number at output 
Word RS5 = Input string address address: 
.O02CT CALL .OO2CT Word 1 « High-order part 
Word 2 = Low-order part 
C = Clear 
Unsuccessful: 
C = Set 
All registers preserved 
Decimal to RO = Address first input byte RO = Address first byte of next string 
Binary CALL $COTB R1 = Converted number 
$COTB R2 = Terminating character 
R3—RS preserved 
Octal to RO = Address first input byte RO = Address first byte of next string 
Binary CALL $COTB R1 =» Converted number 
$COTB R2 = Terminating character 
R3—-RA5 preserved 
ASCII to RO = Address first input Successful: 
Radix-50 character RO = Address next input character 
$CAT5 R1 = 0 (period is terminating Ri = Converted Radix-50 vaiue 
character) R2 = Terminating character 
Ri = 1 (period is valid character) C = Clear 
CALL $CAT5 Unsuccesstul: 
R2 = Illegal character 
C = Set 
R3—RS5 preserved 
ASCil with RO = Address first input Successful: 
Blanks to character RO = Address next input character 
Radix-50 R1 = 0 (period is terminating Ri = Converted Radix-50 value 
$CATSB character) R2 = Terminating character 
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Ri = 1 (period is valid character) 


CALL $CATSB 


C = Clear 
Unsuccessful: 
R2 = Illegal character 
C = Set 
R3--R5 preserved 


Table 9—4 Output Data Conversion Routines Summary 


Summary Procedures 


Routine Name/ 


Input Arguments and - 


Mnemonic Cail Statement Output 

Binary Date RO = Output address Converted date at output address 
Conversion Ri = Binary date RO = Next available output address 
$CBDAT R2 = 0 (zero suppress) R3—RS5 preserved 


Convert Binary 
to Decimal 
Magnitude 
$CBDMG 


Convert Binary 
to Signed 
Decimal 
$CBOSG 


Convert Doubie- 
Precision 

Binary to 
Decimal 
$CDOMG 


Convert Binary 
to Octal 
Magnitude 
$CBOMG 


Convert Binary 
to Signed 


Convert Binary 
Byte to Octal 
Magnitude 
$CBTMG 


R2 = Nonzero (no zero suppress) 
CALL $CBDAT 


RO = Output address 

Ri = Binary number 

R2 = 0 (zero suppress) 

R2 = Nonzero (no zero suppress) 
CALL $CBDMG 


RO = Output address 

Ri = Binary number 

R2 = 0 (zero suppress) 

R2 = Nonzero (no zero suppress) 
CALL $CBDSG 


RO = Output address 

R1 = Input address 

R2 = 0 (zero suppress) 

R2 = Nonzero (no zero suppress) 
CALL $CDDMG 


RO = Output address 

R1 = Binary number 

R2 = 0 (Zero suppress) 

R2 = Nonzero (no zero suppress) 
CALL $CBOMG 


RO = Output address 

Ri = Binary number 

R2 = 0 (zero suppress) 

R2 = Nonzero (no zero suppress) 
CALL $CBOSG 


RO = Output address 

R1 = Binary byte 

R2 = 0 (zero suppress) 

R2 = Nonzero (no zero suppress) 
CALL $CBTMG 


R1i—R2 destroyed 


Converted number at output address 
RO = Next available output address 
R3—RS5 preserved 

Ri—R2 destroyed 


Converted number at output address 
RO = Next available output address 
R3—RS5 preserved 

Ri—R2 destroyed 


Successful: 
Converted number at output 
address 
Unsuccessful: 
String of ASCil asterisks at 
output address 
RO = Next available output address 
R3—RS5 preserved 
Ri—R2 destroyed 


Converted number at output address 
RO = Next available output address 
R3—RS preserved 

R1—R2 destroyed 


Converted number at output address 
RO = Next available output address 
R3—RS5 preserved 

R1—R2 destroyed 


Converted byte at output address 
RO = Next available output address 
R3—R5 preserved 

Ri—R2 destroyed 


Summary Procedures 


Table 9-4 (Cont.) Output Data Conversion Routines Summary 


Routine Name/ 
Mnemonic 


Input Arguments ana 
Call Statement 


General Purpose RO = Output address 


Binary to Ri = Binary vaiue 
ASCil R2 = Conversion parameters: 
$CBTA Bits O—7: = Radix (2 to 1619) 
Bit 8: = 0 = Unsigned value 
= 1 = Signed value 
Bit 9: = O = Zero suppress 
= 1 = No zero 
suppress 
Bit 10: = 1, replace leading 
zeros with blanks 
= 0, do not replace 
leading zeros with 
blanks 
Bits 11—15: = Field width 
(value 1—32) 
CALL $CBTA 
Radix-50 to RO = Output address 
ASCIl R1 = Radix-50 word 
$CSTA CALL $CSTA 


Table 9-5 Output Formatting Routines Summary 


Output 


Converted number at output address 
RO = Next available output address 
R3—RS5 preserved 

Ri—R2 destroyed 


Converted number at output address 
RO = Next available output address 
R3—RS not used 

Ri—Re2 destroyed 


Routine Name/ Input Arguments and 


Mnemonic Call Statement Output 
Uppercase RO = Input address Converted text at output address 
Text R1 = Output address R3—R5 not used 
$CVTUC R2 = Number input bytes R2 destroyed 
(cannot be zero) RO—R1 left pointing to the character following the 
CALL $CVTUC string 
Date String RO = Cutput address Converted date string at output address 
Conversion Ri = Input address RO = Next available output address 
$DAT CALL $O0AT R1 = Address of next input word 
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R3—R5 preserved 
R2 destroyed 


Summary Procedures 


Table 9-5 (Cont.) Output Formatting Routines Summary 


Routine Name/ 
Mnemonic 


Input Arguments and 
Call Statement 


Output 


Time Conversion RO = Output address 
$TIM R1 = Input address 
R2 = Parameter count: 
= 0 or 1, hour (HH) 
= 2, hour:minute 
(HH:MM) 
= 3, hour:minute:second 
(HH:MM:SS) 
=4or 5, 
hour:minute:second. 
tenth of second 
(HH:MM:SS.S) 
CALL $TIM 


Detine ASCIZ input string 
directives in the form: 


Edit Message 
SEDMSG 


%l 
%onil 
Vi 


where n = Optional decimal 

repeat count; V specifies an 

optional value to be used 

as a repeat count; and 

| = One of the following 
characters: 


Converted time string at output address 
RO = Next available output address 

R1 = Address of next input word 
R3—RS5 preserved 


RO—R1 updated 


R2 destroyed 


Converted/formatted data in output block 

RO = Address of last zero byte in output 
block 

Ri = Number of bytes in output block 

R2 = Address of next argument in 
argument block 

R3—RS5 preserved 


Summary Procedures 


Table $—5 (Cont.) Output Formatting Routines Summary 


Routine Name 
Mnemonic 


input Arguments and 
Call Statement Output 


RAE CATERER SENSEI 


A = ASCIil string transfer 

B = Binary byte to octal conversion 

D = Binary to signed decimal conversion 

E = Extended ASCII string transfer 

F = Form control insertion 

| = ASCIZ address 

M = Binary to decimal magnitude conversion, zero suppression 
N = New line insertion 

O = Binary to signed octal conversion 

P = Binary to octal magnitude conversion, no zero suppression 
Q = Binary to octal magnitude conversion, zero suppression 

R = Radix-50 to ASCII conversion 

S = Space insertion 

T = Double-precision binary to decimal conversion 

U = Binary to double-precision decimal conversion, no zero suppression 
X = Filename conversion 

Y = Date conversion 

Z.= Time conversion 

< = Define fixed-length byte field 

> = Locate field mark 


Set up argument and output biock: 
RO = Output address 
Ri = Input string address 
R2 = Argument block address 
CALL $EDMSG 


Table 9-6 Dynamic Memory Management Routines Summary 


Routine Name/ Input Arguments and 


Mnemonic Call Statement Output 
Initialize Include FREEHD: .BLKW 2 RO = Task’s first address 
Dynamic in data section R1 = Free pool first address 
Memory RO = Free memory listhead R2 = Size memory pool 
SINIDM address R3—RS5 not used 
CALL SINIDM 
Request Core RO = Free memory listhead Successful: 
Block address RO = Block memory address 
$ROCB Ri = Byte size of block Ri = Actual size of block 
CALL $RQCB C = Clear 
Unsuccesstul: 
C = Set 
R3—R5 preserved 
R2 destroyed 


Release Core RO = Free memory listhead 
Block address 
$RLCB R1 = Byte size of block 

_ R2 = Block memory address 


Released biock 
R3—R5 preserved 
RO unchanged 
Ri—R2 destroyed 


Summary Procedures 


Table 9-7 Virtual Memory Management Routines Summary 


Routine Name/ 


input Arguments and 


Mnemonic Call Statement Output 
Initialize Define $FRHD block with Successful: 
Virtual first address of free memory RO = 0 
Memory Define 4 global symbols: C = Clear 
SINIVM WSKLUN (work file LUN) Unsuccesstul: 
WS$KEXT (work file RO = —2, file not opened 
extension size) RO = —1, file not marked 
N$MPAG (fast page search C = Set 
page count) R3— RS preserved 
$SWRKPT (address of FOB) Original contents RO—R2 destroyed 
Ri = Free memory highest 
address 
CALL SINIVM 
Allocate R1 = Byte size of requested Successful: 
Block block RO = Block memory address 
$ALBLK CALL $ALBLK Unsuccessful: 
User's SERMSG routine is called 
R3—AS preserved 
RO—R2 destroyed 
Get Core Ri = Byte size of requested Successful: 
$GTCOR block RO = Block memory address 
CALL $GTCOR C = Clear 
Unsuccessful: 
C = Set 
R3—RS5 preserved 
Extend Ri = Byte size of requested Successful: 
Task block R1 = Actual extension size 
$EXTSK CALL $EXTSK C = Clear 
Unsuccessful: 
C = Set | 
R2—RS5 preserved 
Write R2 = Memory address of page Successful: 
Page CALL $WRPAG C = Clear 
SWRPAG Unsuccessful: 
User's SERMSG routine Is called 
RO—R2 preserved 
Allocate Ri = Byte size of requested Successful: 
Virtual block RO = Allocated block memory address 
Memory CALL SALVRT Ri = Allocated block disk address 
Unsuccessful: 


$SALVRT 


User's $ERMSG routine is called 
R3—RS5 preserved 
R2 destroyed 
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Summary Procedures 


Table 9-7 (Cont.) Virtual Memory Management Routines Summary 


Routine Name/ 
Mnemonic 


Input Arguments and 
Call Statement 


Allocate 
Small 
Virtual 
Block 
$ALSVB 


Convert and 
Lock Page 
$CVLOK 


Convert Virtual 
to Real 
Address 
$CVRL 


Read Page 
$RDOPAG 


Find Page 
$FNDPG 


Write-Marked 
Page 
$WRMPG 


Lock Page 
$LCKPG 


Unlock Page 
SUNLPG 
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Define NSDOLGH = = 51210 
Ri = Size of requested page 
block: 
= 0, for large biock 
allocation on first 
cail to $ALSVB 
= A value less than or 
equal to 51215 bytes 
for small page 
allocation 
CALL $ALSVB 


R1 =» Virtual address 
CALL S$CVLOK 


R1 = Virtual address. 
CALL SCVAL 


RO = Page disk address 
CALL $RDPAG 


Ri = Page virtual address 
CALL SFNDPG 


Ri = Virtual address in page 
CALL SWRMPG 


R1 = Virtual address in page 
CALL $LCKPG 


R1 = Virtual address in page 
CALL SUNLPG 


Output 


RO «= Block memory address 
R1 = Block virtual address 
R3—RS5 preserved 

R2 destroyed 


Successful: 
RO = Memory address 
R1 = Virtual address 
C = Clear 
Unsuccessful: 
C m Set 
R2—R5 preserved 


RO = Memory address 
R3—RS preserved 

R1 unchanged 

R2 destroyed 


Successful: 

C = Clear 
Unsuccessful: 

User's $ERMSG routine is called 
RO—R2 preserved 


Page found: 
RO = Block memory address 
C = Clear 

Page not found: 
C = Set 


C = Clear, page write-marked 
C = Set, page not found 
RO—R2 preserved 


C = Clear, page locked 
C = Set, page not found 
RO—R2 preserved 


C = Clear, page unlocked 
C = Set. page not found 
RO—R2 preserved 


System Reference Bibliography 


This bibliography identifies manuals that contain descriptions of additional routines available to 
IAS system library users. 


First level entries are manual titles. Second level entries are functional headings that indicate the 
types of services described in the respective manuals. 


¢ JAS Executive Facilities Reference Manual 
- Task execution control directives 
- Informational directives 
- Event-associated directives 
- Trap-associated directives 
- YO related directives 
- Task status control directives 
e IAS Device Handlers Reference Manual 
~ Laboratory and industrial I/O routines 
¢ IAS I/O Operations Reference Manual 
- YO preparation services 
- File processing services 
~- File control routines 
- File structuring services 
~ Command line processing services 
- Parsing services 


~ Spooling services 


Universal Library Access . 


On most IAS systems, you can create a universal library to store related groups of files. The LBR 
utility creates the universal library file with a file type ULB. By means of the LBR las you can 
subsequently insert files as modules in the library. 


To access a module of a universal library, a program can call the $ULA routine, which sata blishas 

the necessary conditions for access (read only). The $ULA routine first calls an initializing 
routine, SULAIN, to validate that the library file is in the correct format and to obtain the needed 
information from the library header. $ULA then calls a second routine, $ULAFD, to read the 
module header, to position libary file pointers to the beginning of the module, and to establish the 
necessary FDB locations for the File Control System (FCS).2 Once the necessary FDB locations are 
established, the program can access the module as if it were a separate file. That is, the program 
can perform GET$ operations in move mode for each record in the module. 


To call the $ULA routine, supply the following data: 


* In Register 0, the address of the universal library FDB. The library file must already ks open 
for read access. 


* In Register 1, the address of a 423-word buffer. The first two words of the buffer must contain 
the name (in Radix-50 format) of the module to be accessed. $ULA will put a copy of the 
module header from the library into the remaining 100, (649) bytes. Initialize the FDRC$A 
arguments urba and urbs (FDB offsets F. URBD and F. URBD+2) in the FDB for the library file. 
The $ULA routine saves the arguments, uses the space for storing module header ees 
and restores the values before returning control to the calling program. 

The $ULA routine produces the following data: 

* Register 0 is unchanged. 


® Register 1 is unchanged. The $ULA routine fills in the 40-word buffer with a copy of the 
header for the module accessed. 


¢ The first seven words of the library file FDB contain the first seven words of the FDB of the 
module's associated input file (as if it were a separate input file). 


¢ The offset FEEFBK+2 of the library file FDB contains the last block number of the ibdaie: 


© The offset F.FFBY of the library file FDB contains the number of the next available a past 
the end of the module. 


e The offset FEERR of the library file FDB has the standard interpretations except for the 
following special meanings: 


— The symbol IE.BHD means either “File not a universal library” or “Bad library header.” 
— The symbol IE.NSF means “No such module.” 


© The C bit is set to indicate an error. 


in the JAS Command Language Manual. 
2 See the JAS I/O Operations Reference Manual for information on FCS and the use of FDB locations. 


1 See the description of the LBR utility in the JAS Utilities Manual, or see the description of the DCL command LIBRARY 


Universal Library Access 


To use the $ULA routine properly, use the following coding sequence: 


OPENS RO 7; OPEN UNIVERSAL LIB FILE 


7; STORE FIRST SEVEN WORDS OF LIBRARY FDB 
CALL SULA 


GETS RO ? ACCESS MODULE IN MOVE MODE ONLY 


; RESTORE FIRST SEVEN WORDS OF LIBRARY FDB 


CLOSES RO or invoke SULA again 


NOTE: Note that the program must open the library file for read-only access. (To change 
a moduie in the universal library, use the LBR utility.) The program must save the first 
seven words of the library file FDB before calling the $3ULA routine for the first time. 
The $ULA routine modifies these words during processing, but their original values are 
necessary either to access another module or to ensure that the library file is closed 
properly. The program must restore the seven words after accessing a moduie and 
before accessing another module or before closing the library file. 
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$ALBLK (Allocate block) » 8—11 
$ALSVB (Allocate smail virtual biock) » 8-30 
$ALVAT (Allocate virtual memory) » 8-27 
ASCII number conversion 
ASCII to Radix-50 ($CATS) « 4—11 
ASCII with blanks to Radix-50 (SCAT5B) ° 4-13 
decimal to binary 
0 4—7 
double-word (.OD2CT) - 4-3 
octal to binary 
double-word (.OD2CT) «4-5 
octal to binary (SCOTB) « 4—9 


B 


Binary conversion 
°5—16 
binary date to decimal (SCBDAT) « 5-3 
binary to signed decimal (SCBDSG) + 5-7 
binary to signed octal (SCBOSG) - 5—14 
binary to unsigned decimal $CBOMG ° 5—5 
binary to unsigned octal (SCBOMG) « 5-12 
double-precision binary to decimal (SCDDMG) « 
5-9 
general purpose binary to ASCII ($CBTA) - 5-18 


©) 


$C5TA (Radix-50 to ASCil) * 5—20 

$CATS (ASCII to Radix-50) »4—11 

$CATS5B (ASCIl with blanks to Radix-50) « 4-13 
$CBDAT (Binary date to decimal) - 5—3 
$CBDMG (Binary to unsigned decimal) + 5—5 
$CBDSG (Binary to signed decimal) + 5—7 
$CBOMG (Binary to unsigned octal) + 5—12 
$CBOSG (Binary to signed octal) » 5-14 

$CBTA (General purpose binary to ASCIl) « 5~18 
$CBTMG (Binary byte to octal) «5-16 

$CDDMG (Double-precision binary to decimal) - 5-9 
$CDTB (Decimal to binary) » 4~7 


Conversion 
See ASCIl number conversion 
See Binary conversion 
See Date conversion 
See Decimal conversion 
See Octal conversion 
See Radix-50 conversion 
See Time conversion 


| $COTB (Octal to binary) « 4—9 


$CVLOK (Page lock) » 8-37 : 
$CVRL (Virtual to real address) » 8-40 | 
$CVTUC (Uppercase text) » 6-2 


D 


$DAT (Date conversion) 

alternate format » 6-6 

standard format * 6—4 
Date conversion 

alternate format date ($DAT) «6-6 

standard format date ($DAT) » 6—4 
Dates, specifying » 6-8 
$DDIV (Double-precision divide) » 3-5 
Decimal conversion 

decimal to binary 

+47 
double-word (.DD2CT) + 4-3 

$DIV (Integer divide) + 3-3 
Divide routine 

divide ($DIV) * 3-3 

double-precision divide (SODIV) « 3~5 
$DMUL (Double-precision multiply) «3-4 
Double-precision divide ($DDIV) - 3—5 
Double-precision multiply (SDMUL) «34 
Double-precision routine > 3—1 


E 


$SEDMSG (Edit message) « 6-11 
$EXTSK (Extend task) - 8-20 
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Index 


E 


$FNDPG (Find page) « 846 


G 


$GTCOR (Get.core) * 8-17 


SINIDM (Initialize memory) « 7--2 
SINIVM (Initialize virtual memory) - B—6 
Integer routine 

divide ($DIV) « 33 

muitipiy (SMUL) ° 3-2 


L 


$LCKPG (Lock page) » 8-51 
Library routine 
communicating between « 1=1 
placing * 1~2 
searching « 1-2 
storing * 1-2 


M 


Memory management » 7—1 


See also Virtual memory management 
core blocks release (S$ALCE) ° 7-6 
core blocks request (SRQCB) - 7—4 
initialize (S$INIDM) * 7-2 
Message formatting * 6—1 

carriage return/line feed insertion * 6—14 
date conversion (S$DAT) 

alternate format » 6—6 

standard format « 6—4 
edit directive (SEDMSG) «6-11 
extended ASCIil « 613 
field mark « 6—15 
filename string «6-15 
form-feed insertion * 6-13 
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Message formatting (Cont.) 
general - 6—11 
space insertion * 6-14 
time conversion ($TIM) « 6—9 
uppercase text (SCVTUC) + 6-2 
$MUL (Integer multiply) «3-2 
Multiply routine 
double-precision muitiply (SODMUL) ° 3—4 
multiply (SMUL) » 3—2 


N 


Numeric to ASCII « 5—1 
See also ASCII number conversion 
binary byte to octal 
5-16 
binary date to decimal 
“5-3 
binary to signed decimai 
° 5-7 
binary to signed octal 
5-14 
binary to unsigned decimal 
°§—5 
binary to unsigned octal 
“5-12 
double-precision binary to decimal 
“5-9 
general purpose binary to ASCII (SCBTA) « S18 
Radix-50 to ASCII ($CSTA) « 5-20 


O 


Octal conversion 
octal to binary 
double-word (.OD2CT) « 4—5 
octal to binary(SCOTB) » 4—9 
.OD2CT 
Octal to binary, double-word + 4-5 


p 


Paging, memory 
See Virtual memory management 
Programming conventions . 
general « 1-1 


mt 


Radix-50 conversion 
ASCIl to Radix-50 (SCATS5) * 4—11 
ASCII with blanks to Radix-50 ($CAT5B) * 4-13 
Radix-50 to ASCII (SCSTA) »* 5~20 
$SRDOPAG (Read page) * 8—43 
Register handling 
of control swapping function « 2—1 
save ail Registers (SSAVAL) « 2-3 
save Registers 0-2 (SSAVVR) « 2-7 
save Registers 1-5 (.SAVR1) * 2-8 
save Registers 3-5 (SSAVRG) « 2—5 
$RLCB (Release core block) + 7-6 
$RQCB (Request core biocks) « 7—4 
SRQVCS (Request virtual core block) » 8-34 


Oe 


$SAVAL (Save ail Registers) -2~—3 
.<SAVR1 (Save Registers 1-5) « 2-8 
$SAVRG (Save Registers 3-5) » 2-5 
$SAVVR (Save Registers 0-2) » 2-7 
Single-precision routine 


See Integer routine 


— 


$TIM (Time conversion) « 6-9 
Time conversion 
time ($TIM) * 6—9 


Cc 


SULA (Universal library) » B—1 
Universal library 

creating » B—1 
SUNLPG (Unlock page) « 8-54 


V , 


Virtual memory management ¢ 8—1 


Index 


Virtual memory management (Cont.) 
See also Memory management 
address conversion ($CVRL) * 8—40 
allocate (S$ALVRT) « 8-27 
allocate small virtual block (SALSVB) * 6-30. 
core blocks request ($RQVCB) » 834 
$CVRL routine - 840 
error-handling » 8—2 
find page (SFNDPG) » 8-46 
initialize (SINIVM) « 8—6 
lock page ($LCKPG) « 8-51 
memory storage 

allocate block (SALBLK) « 8—11 

extend task (SEXTSK) + 8-20 

get core ($GTCOR) ¢ 8-14, 8-17 
page lock (S$CVLOK) « 8-37 
read page (S$RDPAG) - 8—43 
task building requirements * 8-3 
unlock page (SUNLPG) ¢ 8-54 
write-marked page (SWRMPG) « 618 
write page (SWRPAG) « 8-23 


W 


SWRMPG (Write-marked page) » 8—48 
SWRPAG (Write page) « 8-23 
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